feat(#194): update help documentation for PlatyPS compatibility

- Clarify workflow for generating help files by emphasizing the need to build and import the dist module first.
- Update instructions to ensure correct metadata fields are populated in help files.
- Add guidance on maintaining consistent naming conventions for external help files.

Author: stiwicourage

.github/agents/powershell-developer.agent.md

@@ -47,7 +47,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Keep new or heavily changed source functions aligned with `.github/instructions/code-quality-matrix.instructions.md`: short, single-purpose, low-duplication, and split by clear responsibility unless the scope explicitly justifies otherwise.
 - Prefer `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` for normal analyzer loops; use direct `Invoke-ScriptAnalyzer` only for focused local checks that reuse the repository-approved settings.
 - Validate Nova-managed project tests through `Test-NovaBuild`; do not call `Invoke-Pester` directly.
-- When help files change, keep `docs/NovaModuleTools/en-US/*.md` valid for `Import-MarkdownCommandHelp`: use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. A new public `src/public/*.ps1` file is not done until its matching help file exists.
+- When help files change, keep `docs/NovaModuleTools/en-US/*.md` valid for `Import-MarkdownCommandHelp`: build and import the dist module first (`Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force`), then use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. Generating help without the module imported causes `external help file` to default to the command name instead of the module name, producing per-command XML files that the manifest cannot find. A new public `src/public/*.ps1` file is not done until its matching help file exists.
 
 ## Definition of done
 

.github/agents/reviewer.agent.md

@@ -22,6 +22,7 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - Check changed PowerShell code, tests, and examples against `project.json` `Manifest.PowerShellHostVersion`; flag PowerShell 7.x-only constructs in projects that target `5.1` unless the change explicitly adds guarded compatibility handling.
 - Check that public commands/classes have matching valid PlatyPS-compatible help and that new source files have source-mirrored tests. Flag help files under `docs/NovaModuleTools/en-US/` that look like plain Markdown, break the required PlatyPS section order, or would fail `Test-MarkdownCommandHelp` / `Import-MarkdownCommandHelp`.
 - Flag any new public entry point that does not add its matching help file in the same change.
+- Flag help files where `external help file` contains a command name instead of the module name. The correct value is `NovaModuleTools-Help.xml`; a per-command name like `Get-Something-Help.xml` means the help was generated without the built module imported.
 - Check analyzer changes and PowerShell validation flow against `.github/instructions/psscriptanalyzer.instructions.md`. Flag direct `Invoke-ScriptAnalyzer` usage that bypasses repository-approved settings or wrapper semantics without a clear reason.
 - Review changed `src/**/*.ps1` against `.github/instructions/code-quality-matrix.instructions.md` and `tests/**/*.ps1` against `.github/instructions/testing-policy.instructions.md`; flag new or heavily changed code that ignores those maintainability rules without a clear, explicit reason.
 - Flag public files that do not keep exactly one top-level function, and flag private files that group multiple externally called functions instead of limiting extra functions to related same-file top-level support helpers. Also flag file/function name mismatches for public commands or externally called private helpers, and flag nested function declarations inside PowerShell functions.

.github/instructions/platyps-help.instructions.md

@@ -15,8 +15,14 @@ Use this file when creating or updating command help under `docs/NovaModuleTools
 
 ## Required workflow
 
-1. Load the command surface you are documenting before you touch the help files.
-2. For new command help, generate the initial skeleton with `New-MarkdownCommandHelp` from the actual commands rather than starting from a blank Markdown file.
+1. Build and import the dist module before generating or updating help files. This ensures PlatyPS picks up the correct module name for both the `Module Name` and `external help file` metadata fields.
+
+```powershell
+Invoke-NovaBuild
+Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force
+```
+
+2. For new command help, generate the initial skeleton with `New-MarkdownCommandHelp` from the imported module commands rather than starting from a blank Markdown file.
 
 ```powershell
 $newMarkdownHelp = @{
@@ -57,6 +63,7 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - Keep one command-help file per public entry point, and match the markdown file name to the command name.
 - Keep the YAML metadata block at the top of every help file, delimited by `---`.
 - Keep the metadata aligned with the command being documented. At minimum, preserve the same metadata keys used by the repository's existing valid help files, including `document type`, `external help file`, `HelpUri`, `Locale`, `Module Name`, `ms.date`, `PlatyPS schema version`, and `title`.
+- The `external help file` field must always use the module name, not the command name: `NovaModuleTools-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `<ModuleName>-Help.xml` under `dist/<ModuleName>/en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help.
 - Keep the H1 title equal to the exact command name.
 - Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`.
 - Keep at least one example under `## EXAMPLES`.
@@ -68,6 +75,7 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 
 ## Authoring guidance
 
+- Always import the built dist module (`Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force`) before running `New-MarkdownCommandHelp` or `Update-MarkdownCommandHelp`. Generating help without the module imported causes PlatyPS to default `external help file` to the command name instead of the module name, which produces per-command XML files that the module manifest cannot find.
 - Prefer generating the initial help shape from the actual public command so syntax and parameter blocks stay aligned with the implementation.
 - When source adds a new public entry point, create the matching help file immediately in the same change even if the narrative text still needs follow-up refinement.
 - When editing an existing help file, preserve the YAML metadata and parameter sections unless you intentionally regenerate the file from the command surface.
@@ -79,6 +87,7 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 ## Review expectations
 
 - Reviewers should flag help files that lack YAML metadata, break the expected PlatyPS section structure, skip the `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` workflow, or look like plain Markdown prose instead of command help.
+- Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`NovaModuleTools-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime.
 - Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`.
 - Reviewers should flag any new public entry point that does not add its matching command-help file in the same change.
 - Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet.

.github/skills/powershell-module-development/SKILL.md

@@ -38,7 +38,7 @@ Use this skill when changing public commands, private helpers, CLI routing suppo
 - Keep `run.ps1`-style local checks ordered as ScriptAnalyzer first, then `Invoke-NovaBuild`, then `Test-NovaBuild`.
 - If `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1` reports ScriptAnalyzer findings, fix them before handoff instead of just reporting the failure.
 - Before handoff, review every changed or generated text file and normalize it to exactly one trailing newline with no extra blank lines at the end.
-- Add or update valid PlatyPS-compatible help under `docs/NovaModuleTools/en-US/` when public commands or public classes change. Use `New-MarkdownCommandHelp` for new help, `Update-MarkdownCommandHelp` to refresh existing help metadata, and `Test-MarkdownCommandHelp` to validate structure before handoff instead of writing plain Markdown from scratch.
+- Add or update valid PlatyPS-compatible help under `docs/NovaModuleTools/en-US/` when public commands or public classes change. Always build and import the dist module first (`Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force`) before running `New-MarkdownCommandHelp` or `Update-MarkdownCommandHelp`, so PlatyPS writes the module name — not the command name — into `external help file` and `Module Name`. Use `Test-MarkdownCommandHelp` to validate structure before handoff instead of writing plain Markdown from scratch.
 - For every new public `src/public/*.ps1` file, create the matching help file immediately in the same change.
 - Add or update the source-mirrored Pester test file for every changed `src/**/*.ps1` file.
 
@@ -54,6 +54,7 @@ Use this skill when changing public commands, private helpers, CLI routing suppo
 - Ignoring the source-code guidance and letting new or heavily changed functions grow long, deeply nested, duplicated, or multi-purpose without justification
 - Writing plain Markdown under `docs/NovaModuleTools/en-US/` that lacks YAML metadata or the PlatyPS structure expected by `Import-MarkdownCommandHelp`
 - Editing PlatyPS YAML and section structure by hand when `New-MarkdownCommandHelp` or `Update-MarkdownCommandHelp` should have regenerated it
+- Generating help markdown without the built module imported, which causes `external help file` to default to the command name and produces per-command XML files instead of a single `<ModuleName>-Help.xml`
 - Adding a new public entry point without the matching help file in `docs/NovaModuleTools/en-US/`
 - Bypassing the repository analyzer wrapper/settings with ad hoc `Invoke-ScriptAnalyzer`, `-EnableExit`, or broad rule-exclusion changes
 - Ignoring the project's `Manifest.PowerShellHostVersion` target and introducing PowerShell 7.x-only features into a `5.1` project

src/resources/agentic-copilot/.github/agents/powershell-developer.agent.md

@@ -44,7 +44,7 @@ Implement PowerShell command and helper changes in the {{ProjectName}} style.
 - Keep new or heavily changed source functions aligned with `.github/instructions/code-quality-matrix.instructions.md`: short, single-purpose, low-duplication, and split by clear responsibility unless the scope explicitly justifies otherwise.
 - Prefer `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` for normal analyzer loops; use direct `Invoke-ScriptAnalyzer` only for focused local checks that reuse the repository-approved settings.
 - Validate Nova-managed project tests through `Test-NovaBuild`; do not call `Invoke-Pester` directly.
-- When help files change, keep `docs/{{ProjectName}}/en-US/*.md` valid for `Import-MarkdownCommandHelp`: use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. A new public `src/public/*.ps1` file is not done until its matching help file exists.
+- When help files change, keep `docs/{{ProjectName}}/en-US/*.md` valid for `Import-MarkdownCommandHelp`: build and import the dist module first (`Import-Module ./dist/{{ProjectName}}/{{ProjectName}}.psd1 -Force`), then use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. Generating help without the module imported causes `external help file` to default to the command name instead of the module name, producing per-command XML files that the manifest cannot find. A new public `src/public/*.ps1` file is not done until its matching help file exists.
 
 ## Definition of done
 

src/resources/agentic-copilot/.github/agents/reviewer.agent.md

@@ -22,6 +22,7 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - Check changed PowerShell code, tests, and examples against `project.json` `Manifest.PowerShellHostVersion`; flag PowerShell 7.x-only constructs in projects that target `5.1` unless the change explicitly adds guarded compatibility handling.
 - Check that public commands/classes have matching valid PlatyPS-compatible help and that new source files have source-mirrored tests. Flag help files under `docs/{{ProjectName}}/en-US/` that look like plain Markdown, break the required PlatyPS section order, or would fail `Test-MarkdownCommandHelp` / `Import-MarkdownCommandHelp`.
 - Flag any new public entry point that does not add its matching help file in the same change.
+- Flag help files where `external help file` contains a command name instead of the module name. The correct value is `{{ProjectName}}-Help.xml`; a per-command name like `Get-Something-Help.xml` means the help was generated without the built module imported.
 - Check analyzer changes and PowerShell validation flow against `.github/instructions/psscriptanalyzer.instructions.md`. Flag direct `Invoke-ScriptAnalyzer` usage that bypasses repository-approved settings or wrapper semantics without a clear reason.
 - Review changed `src/**/*.ps1` against `.github/instructions/code-quality-matrix.instructions.md` and `tests/**/*.ps1` against `.github/instructions/testing-policy.instructions.md`; flag new or heavily changed code that ignores those maintainability rules without a clear, explicit reason.
 - Flag public files that do not keep exactly one top-level function, and flag private files that group multiple externally called functions instead of limiting extra functions to related same-file top-level support helpers. Also flag file/function name mismatches for public commands or externally called private helpers, and flag nested function declarations inside PowerShell functions.

src/resources/agentic-copilot/.github/instructions/platyps-help.instructions.md

@@ -15,8 +15,14 @@ Use this file when creating or updating command help under `docs/{{ProjectName}}
 
 ## Required workflow
 
-1. Load the command surface you are documenting before you touch the help files.
-2. For new command help, generate the initial skeleton with `New-MarkdownCommandHelp` from the actual commands rather than starting from a blank Markdown file.
+1. Build and import the dist module before generating or updating help files. This ensures PlatyPS picks up the correct module name for both the `Module Name` and `external help file` metadata fields.
+
+```powershell
+Invoke-NovaBuild
+Import-Module ./dist/{{ProjectName}}/{{ProjectName}}.psd1 -Force
+```
+
+2. For new command help, generate the initial skeleton with `New-MarkdownCommandHelp` from the imported module commands rather than starting from a blank Markdown file.
 
 ```powershell
 $newMarkdownHelp = @{
@@ -57,6 +63,7 @@ Import-MarkdownCommandHelp -Path ./docs/{{ProjectName}}/en-US/<CommandName>.md |
 - Keep one command-help file per public entry point, and match the markdown file name to the command name.
 - Keep the YAML metadata block at the top of every help file, delimited by `---`.
 - Keep the metadata aligned with the command being documented. At minimum, preserve the same metadata keys used by the repository's existing valid help files, including `document type`, `external help file`, `HelpUri`, `Locale`, `Module Name`, `ms.date`, `PlatyPS schema version`, and `title`.
+- The `external help file` field must always use the module name, not the command name: `{{ProjectName}}-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `<ModuleName>-Help.xml` under `dist/<ModuleName>/en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help.
 - Keep the H1 title equal to the exact command name.
 - Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`.
 - Keep at least one example under `## EXAMPLES`.
@@ -68,6 +75,7 @@ Import-MarkdownCommandHelp -Path ./docs/{{ProjectName}}/en-US/<CommandName>.md |
 
 ## Authoring guidance
 
+- Always import the built dist module (`Import-Module ./dist/{{ProjectName}}/{{ProjectName}}.psd1 -Force`) before running `New-MarkdownCommandHelp` or `Update-MarkdownCommandHelp`. Generating help without the module imported causes PlatyPS to default `external help file` to the command name instead of the module name, which produces per-command XML files that the module manifest cannot find.
 - Prefer generating the initial help shape from the actual public command so syntax and parameter blocks stay aligned with the implementation.
 - When source adds a new public entry point, create the matching help file immediately in the same change even if the narrative text still needs follow-up refinement.
 - When editing an existing help file, preserve the YAML metadata and parameter sections unless you intentionally regenerate the file from the command surface.
@@ -79,6 +87,7 @@ Import-MarkdownCommandHelp -Path ./docs/{{ProjectName}}/en-US/<CommandName>.md |
 ## Review expectations
 
 - Reviewers should flag help files that lack YAML metadata, break the expected PlatyPS section structure, skip the `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` workflow, or look like plain Markdown prose instead of command help.
+- Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`{{ProjectName}}-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime.
 - Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`.
 - Reviewers should flag any new public entry point that does not add its matching command-help file in the same change.
 - Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet.