Group module standards with reference documentation

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

docs/content/Modules/Catalog/index.md

@@ -1,13 +1,23 @@
-# Module development foundations
+# Modules
 
-Process-PSModule is the framework for building, testing, versioning, documenting, and publishing PowerShell modules. These foundations define the repository, source, test, and release conventions that the framework supports and validates.
+This page indexes modules maintained in the PSModule organization and what each module does.
 
-Start with the [Process-PSModule overview](../index.md) to understand the workflow. Use these pages when creating or maintaining a module that runs through it.
+Modules are separate from the [Process-PSModule framework](../index.md). Use the framework documentation to build and release a module; use this page to discover the modules available to install and use.
 
-| Page | Use it for |
-| --- | --- |
-| [Repository Standard](Repository-Standard.md) | Creating a module repository with the required metadata, files, and framework wiring. |
-| [PowerShell module standard](Standards.md) | Structuring source code, designing functions, and applying module-specific conventions. |
-| [Module types](Module-Types.md) | Applying conventions for integration (API) and data modules. |
-| [Test Specification](Test-Specification.md) | Writing consistent, comprehensive Pester tests for module functions. |
-| [Versioning](Versioning.md) | Choosing semantic version changes from the module's public API impact. |
+## Scope
+
+Each module page should capture:
+
+- purpose and problem statement
+- install and import baseline
+- key exported capabilities
+- owner and maintenance notes
+- lifecycle status
+
+## Module index generation
+
+The module list and linked module pages are generated from PSModule repository metadata and README content, then refreshed automatically.
+
+<!-- MODULE_CATALOG_START -->
+
+<!-- MODULE_CATALOG_END -->

docs/content/Modules/index.md

@@ -9,7 +9,7 @@ A brand-new module usually has a small **load-bearing core**: the piece(s) every
 
 ## Identify the load-bearing core first
 
-What counts as "load-bearing" follows the module's archetype from [Module types](../Modules/Module-Types.md):
+What counts as "load-bearing" follows the module's archetype from [Module types](../reference/module-types.md):
 
 - **Data modules** — the conversion pivot: `ConvertFrom-<Format>` / `ConvertTo-<Format>` (and whatever parser/serializer they wrap). Every other function (`Import-`, `Export-`, `Format-`, `Merge-`, ...) is built on top of this pivot and is meaningless without it.
 - **Integration (API) modules** — a [`Context`](https://github.com/PSModule/Context)-backed credential/config store, the client setup that uses it, and at least one API function that consumes the context end-to-end. Every other API function needs the same context and client to do anything.
@@ -25,7 +25,7 @@ Scope the integration branch to exactly that core, not to everything planned for
 
 ## After the core lands
 
-Once the core has merged as `v1.0.0`, ordinary [SemVer](../Modules/Versioning.md) applies: a new function built on the stable core is a **minor** bump, a fix is a **patch** bump, and only a change to the core's own contract (signature, exported class shape, behavior) is a **major** bump. No special versioning exception is needed once the core is in place — the bootstrap phase exists only to get that core to a first release quickly.
+Once the core has merged as `v1.0.0`, ordinary [SemVer](../reference/versioning.md) applies: a new function built on the stable core is a **minor** bump, a fix is a **patch** bump, and only a change to the core's own contract (signature, exported class shape, behavior) is a **major** bump. No special versioning exception is needed once the core is in place — the bootstrap phase exists only to get that core to a first release quickly.
 
 ```mermaid
 gitGraph

docs/content/get-started/module-bootstrap.md

@@ -17,8 +17,8 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
 
    Check:
 
-   - the module still follows the right archetype from [Module types](../Modules/Module-Types.md)
-   - the change respects the layout, private-helper boundaries, context rules, and SOLID guidance in [PowerShell module standard](../Modules/Standards.md)
+   - the module still follows the right archetype from [Module types](../reference/module-types.md)
+   - the change respects the layout, private-helper boundaries, context rules, and SOLID guidance in [PowerShell module standard](../reference/powershell-module-standard.md)
    - the function belongs in this module instead of a different module, a shared helper, or a follow-up issue
 
    A human contributor or agent should be able to explain why this change belongs in this module, in this shape, without inventing new local rules.
@@ -29,8 +29,8 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
 
    Check:
 
-   - `README.md` still answers the start-page questions and reflects any user-visible behavior, prerequisites, or setup changes from [Repository Standard](../Modules/Repository-Standard.md#readme-default)
-   - the relevant public command-group overview page (`src/functions/public/<Group>/<Group>.md`) exists or is updated when the change affects that group's purpose or usage, per [PowerShell module standard](../Modules/Standards.md#repository-layout)
+   - `README.md` still answers the start-page questions and reflects any user-visible behavior, prerequisites, or setup changes from [Repository Standard](../reference/repository-standard.md#readme-default)
+   - the relevant public command-group overview page (`src/functions/public/<Group>/<Group>.md`) exists or is updated when the change affects that group's purpose or usage, per [PowerShell module standard](../reference/powershell-module-standard.md#repository-layout)
    - any module-level documentation under `docs/` or other published surfaces is updated when the change adds or changes guidance that should not live only in comment-based help
 
    If the change teaches the user something new, confirm that the user can discover it from the published documentation surfaces, not only from the diff.
@@ -42,7 +42,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
    Check:
 
    - public functions live under `src/functions/public/<Group>/` and private helpers live under `src/functions/private/<Group>/`
-   - file placement, grouping, and exported surface match [Structuring your module](structuring-your-module.md) and the layout rules in [PowerShell module standard](../Modules/Standards.md#repository-layout)
+   - file placement, grouping, and exported surface match [Structuring your module](structuring-your-module.md) and the layout rules in [PowerShell module standard](../reference/powershell-module-standard.md#repository-layout)
    - there are no nested helper functions, multi-function files, or naming shortcuts that break the "one declaration per file" rule
 
    This step is about shape, not behavior: the goal is that a reader or tool can find the module surface and its helpers exactly where PSModule expects them.
@@ -66,7 +66,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
    Check:
 
    - advanced-function structure, parameter typing and validation, `ShouldProcess`, output behavior, and error handling align with [MSX PowerShell](https://msx.no/docs/Coding-Standards/PowerShell/) and [MSX PowerShell Functions](https://msx.no/docs/Coding-Standards/PowerShell/Functions/)
-   - the code also satisfies the PSModule-specific conventions in [PowerShell module standard](../Modules/Standards.md), especially around private helpers, context handling, and repository layout
+   - the code also satisfies the PSModule-specific conventions in [PowerShell module standard](../reference/powershell-module-standard.md), especially around private helpers, context handling, and repository layout
    - PSScriptAnalyzer warnings are addressed or intentionally justified, but review does not stop there; also look for awkward parameter design, leaky transport details, non-idiomatic output, or code that technically passes lint but is not good PowerShell
 
    PSScriptAnalyzer is part of the validation loop, not the whole loop.
@@ -87,8 +87,8 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
 
 - [MSX Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build)
 - [MSX Implement guidance](https://msx.no/docs/Agents/implement/)
-- [PowerShell module standard](../Modules/Standards.md)
-- [Module types](../Modules/Module-Types.md)
+- [PowerShell module standard](../reference/powershell-module-standard.md)
+- [Module types](../reference/module-types.md)
 - [Structuring your module](structuring-your-module.md)
-- [Repository Standard](../Modules/Repository-Standard.md)
+- [Repository Standard](../reference/repository-standard.md)
 - [MSX Coding Standards](https://msx.no/docs/Coding-Standards/)

docs/content/guides/validating-before-review.md

@@ -74,4 +74,4 @@ pattern used for larger efforts.
 
 - [Your first release](../get-started/your-first-release.md) — the pull request flow end-to-end.
 - [Pipeline stages](../reference/pipeline-stages.md#publish-module) — what the publish job does.
-- [Versioning](../Modules/Versioning.md) — the PSModule versioning policy.
+- [Versioning](../reference/versioning.md) — the PSModule versioning policy.

docs/content/guides/versioning-and-releases.md

@@ -25,19 +25,6 @@ New to Process-PSModule? Work through these in order.
 | [Repository setup](get-started/repository-setup.md) | Configure GitHub Pages, the PowerShell Gallery API key, permissions, and the caller workflow. |
 | [Your first release](get-started/your-first-release.md) | The pull request flow, version labels, and what happens on merge. |
 
-## Module development foundations
-
-The framework automates a module's lifecycle; these conventions define the module it builds and releases.
-
-| Page | Description |
-| --- | --- |
-| [Module development foundations](Modules/index.md) | The full set of module-authoring conventions supported by the framework. |
-| [Repository Standard](Modules/Repository-Standard.md) | Required repository files, metadata, onboarding, and workflow wiring. |
-| [PowerShell module standard](Modules/Standards.md) | Source layout, function design, and module-specific implementation conventions. |
-| [Module types](Modules/Module-Types.md) | Conventions for integration (API) and data modules. |
-| [Test Specification](Modules/Test-Specification.md) | Consistent Pester test structure and coverage expectations. |
-| [Versioning](Modules/Versioning.md) | Semantic version changes based on public API impact. |
-
 ## Guides
 
 Task-oriented deep dives into the pipeline's functionality.
@@ -54,10 +41,16 @@ Task-oriented deep dives into the pipeline's functionality.
 
 ## Reference
 
-Look up the exact contract.
+Look up the framework's exact contracts and the module-development standards it supports.
 
 | Page | Description |
 | --- | --- |
+| [Module development foundations](reference/module-development-foundations.md) | The full set of module-authoring conventions supported by the framework. |
+| [Repository Standard](reference/repository-standard.md) | Required repository files, metadata, onboarding, and workflow wiring. |
+| [PowerShell module standard](reference/powershell-module-standard.md) | Source layout, function design, and module-specific implementation conventions. |
+| [Module types](reference/module-types.md) | Conventions for integration (API) and data modules. |
+| [Test Specification](reference/test-specification.md) | Consistent Pester test structure and coverage expectations. |
+| [Versioning](reference/versioning.md) | Semantic version changes based on public API impact. |
 | [Settings](reference/settings.md) | Every available setting in `.github/PSModule.yml` and the full defaults. |
 | [Workflow inputs](reference/workflow-inputs.md) | Inputs, secrets, and permissions of the reusable workflow. |
 | [Pipeline stages](reference/pipeline-stages.md) | The job-by-job breakdown, from Plan through Publish Docs. |

docs/content/index.md

@@ -0,0 +1,13 @@
+# Module development foundations
+
+Process-PSModule is the framework for building, testing, versioning, documenting, and publishing PowerShell modules. These foundations define the repository, source, test, and release conventions that the framework supports and validates.
+
+Start with the [Process-PSModule overview](../index.md) to understand the workflow. Use these pages when creating or maintaining a module that runs through it.
+
+| Page | Use it for |
+| --- | --- |
+| [Repository Standard](repository-standard.md) | Creating a module repository with the required metadata, files, and framework wiring. |
+| [PowerShell module standard](powershell-module-standard.md) | Structuring source code, designing functions, and applying module-specific conventions. |
+| [Module types](module-types.md) | Applying conventions for integration (API) and data modules. |
+| [Test Specification](test-specification.md) | Writing consistent, comprehensive Pester tests for module functions. |
+| [Versioning](versioning.md) | Choosing semantic version changes from the module's public API impact. |

docs/content/reference/module-development-foundations.md

@@ -1,7 +1,7 @@
 # Module types
 
 Most PSModule modules fall into one of a few archetypes. The general rules in
-[PowerShell module standard](Standards.md) and [MSX PowerShell Standards](https://msx.no/docs/Coding-Standards/PowerShell/) always apply; this
+[PowerShell module standard](powershell-module-standard.md) and [MSX PowerShell Standards](https://msx.no/docs/Coding-Standards/PowerShell/) always apply; this
 page adds the conventions that are specific to a module's type so that modules of the same kind feel
 the same to use.
 
@@ -41,7 +41,7 @@ or hide this abstraction is a design choice:
 
 - **Private transport** (common): Keep REST, GraphQL, and HTTP helpers private. Public functions
   accept resolved inputs and typed objects. This follows the Dependency Inversion rule from
-  [Standards](Standards.md#solid-applied) applied to the network boundary.
+  [Standards](powershell-module-standard.md#solid-applied) applied to the network boundary.
 - **Public transport**: Expose REST or GraphQL functions publicly for power users or module
   composition.
 - **Public Context**: Expose the `Context` module as public so users can configure and manage
@@ -102,5 +102,5 @@ The `Hashtable` module demonstrates the full set: `ConvertFrom-Hashtable`, `Conv
 
 ## Where this connects
 
-- [PowerShell module standard](Standards.md): layout, private functions, and the mandatory context parameter.
-- [Repository Standard](Repository-Standard.md): repository files, README shape, and agent onboarding.
+- [PowerShell module standard](powershell-module-standard.md): layout, private functions, and the mandatory context parameter.
+- [Repository Standard](repository-standard.md): repository files, README shape, and agent onboarding.

docs/content/Modules/Module-Types.md docs/content/reference/module-types.mddocs/content/Modules/Module-Types.md renamed to docs/content/reference/module-types.md

@@ -4,7 +4,7 @@ This is the PSModule organization's Repository Standard. It applies to the PSMod
 
 This standard operates at the same altitude as the [MSX Enterprise Repository Standard](https://msx.no/docs/Ways-of-Working/Repository-Standard/): MSX sets the enterprise-wide default, and this standard adds to and adjusts that default for PowerShell module repositories. Rules this standard does not change are inherited from the MSX default; where this standard adds or overrides a rule, it governs PowerShell module repositories.
 
-The implementation standard still lives in [PowerShell module standard](Standards.md). Type-specific conventions for integration (API) and data modules live in [Module types](Module-Types.md). This page covers the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
+The implementation standard still lives in [PowerShell module standard](powershell-module-standard.md). Type-specific conventions for integration (API) and data modules live in [Module types](module-types.md). This page covers the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
 
 ## Scope
 
@@ -106,7 +106,7 @@ Module repositories use the PSModule framework layout:
 | `tests/` | Pester tests and test data. |
 | `icon/` | Module icon assets. |
 
-Detailed source layout rules live in [PowerShell module standard](Standards.md#repository-layout).
+Detailed source layout rules live in [PowerShell module standard](powershell-module-standard.md#repository-layout).
 
 ### Caller workflow and reusable workflow
 
@@ -227,7 +227,7 @@ Dependabot PRs still go through normal review. Automated dependency updates are
 
 Dependabot's valid `package-ecosystem` values are enumerated in its configuration parser ([`common/lib/dependabot/config/file.rb`](https://github.com/dependabot/dependabot-core/blob/main/common/lib/dependabot/config/file.rb)) and listed in the [Dependabot options reference](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#package-ecosystem). Configure only values from that list: `powershell` is not among them, and an unsupported value makes `.github/dependabot.yml` invalid, which puts the repository's whole Dependabot configuration at risk, including the `github-actions` entry that does work.
 
-PowerShell module dependencies are therefore declared with `#Requires -Modules` in the function files that use them, as described in [PowerShell module standard](Standards.md), and the build collects them into the compiled manifest. Keeping those declarations current is a review responsibility.
+PowerShell module dependencies are therefore declared with `#Requires -Modules` in the function files that use them, as described in [PowerShell module standard](powershell-module-standard.md), and the build collects them into the compiled manifest. Keeping those declarations current is a review responsibility.
 
 A PowerShell ecosystem is proposed in [dependabot/dependabot-core#15501](https://github.com/dependabot/dependabot-core/issues/15501) and implemented in [dependabot/dependabot-core#15666](https://github.com/dependabot/dependabot-core/pull/15666), covering PowerShell's native declarations — `#Requires -Modules` in `.ps1` and `.psm1` files, and `RequiredModules` in a `.psd1` manifest — resolved against the PowerShell Gallery. Adopt it once it ships and `powershell` appears in the options reference, updating this section and the `dependabot.yml` that `Template-PSModule` distributes together.
 
@@ -379,7 +379,7 @@ Default expectations:
 - Source changes under `src/` are module-impacting and should trigger the full module workflow.
 - README and documentation changes should update the site without pretending to be module API changes.
 
-See [Versioning](Versioning.md) for semantic version rules and [PowerShell module standard](Standards.md#cicd-pipeline) for the Process-PSModule pipeline.
+See [Versioning](versioning.md) for semantic version rules and [PowerShell module standard](powershell-module-standard.md#cicd-pipeline) for the Process-PSModule pipeline.
 
 ## Template maintenance