diff --git a/src/docs/Capabilities/index.md b/src/docs/Capabilities/index.md
index 90b170c..9c55a94 100644
--- a/src/docs/Capabilities/index.md
+++ b/src/docs/Capabilities/index.md
@@ -27,7 +27,6 @@ the same spec-and-design shape as any other capability.
| [Deployment](deployment/index.md) | How a change to managed resources is approved together with its effect and deployed exactly as approved — one spec, and one design for each combination of deploying a service provider from a CI/CD platform. |
| [VS Code Extension Framework](vscode-extension-framework/index.md) | How a VS Code extension is built, tested, versioned, packaged, and published — one GitHub-native pipeline, opt-in from a template and a single settings file. |
| [PowerShell on GitHub](powershell-on-github/index.md) | How we make GitHub a first-class platform for PowerShell through reusable modules, actions, and capability gaps we close over time. |
-| [Process-PSModule](process-psmodule/index.md) | The end-to-end PowerShell module pipeline — what it must guarantee and how it is built, alongside reference documentation for configuration and deployment. |
| [Agentic Development](agentic-development/index.md) | The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behavior. |
diff --git a/src/docs/Capabilities/powershell-on-github/design.md b/src/docs/Capabilities/powershell-on-github/design.md
index edc5637..d399fd9 100644
--- a/src/docs/Capabilities/powershell-on-github/design.md
+++ b/src/docs/Capabilities/powershell-on-github/design.md
@@ -32,7 +32,7 @@ The model combines two tracks:
## Current canonical references
- PSModule initiative overview: ../../Initiatives/PSModule.md
-- Process-PSModule capability: ../../Capabilities/process-psmodule/index.md
+- [Process-PSModule documentation](https://psmodule.io/docs/Modules/Process-PSModule/)
- Coding standards baseline: ../../Coding-Standards/index.md
## Planned evolution
diff --git a/src/docs/Capabilities/process-psmodule/configuration.md b/src/docs/Capabilities/process-psmodule/configuration.md
deleted file mode 100644
index 86e1b9e..0000000
--- a/src/docs/Capabilities/process-psmodule/configuration.md
+++ /dev/null
@@ -1,315 +0,0 @@
----
-title: Configuration
-description: The Process-PSModule settings file — every available setting, the full defaults, and worked examples for coverage, rapid testing, linting, and release notes.
----
-
-# Configuration
-
-The workflow is configured using a settings file in the module repository.
-The file can be a `JSON`, `YAML`, or `PSD1` file. By default, it will look for `.github/PSModule.yml`.
-
-The settings listed on this page are the user-facing configuration contract in `.github/PSModule.yml`. During the
-Plan phase, Process-PSModule enriches this input into an internal runtime `Settings` object that downstream workflows
-consume. Internal runtime paths in workflow docs (for example, `Settings.Publish.Module.Resolution.*`) describe that
-enriched inter-workflow contract, not a different authoring format for repository settings files.
-
-Simple, Standard, and Advanced test profiles are repository conventions, not settings. `.github/PSModule.yml` has no
-layout or suite-matrix selector; Process-PSModule [discovers the files under `tests/` recursively](pipeline-stages.md#module-local-test-discovery)
-and computes its internal `Settings.Test.Module.Suites` matrix from them.
-
-Test discovery and change triggering are separate. The default `ImportantFilePatterns` match only `^src/` and
-`^README\.md$`, so a test-only change does not enter the important-change build, test, and publish path. Repositories
-that need test or automation changes to exercise that path must [add `^tests/` and any relevant settings or workflow
-paths](usage.md#customizing-important-file-patterns) while retaining every default they still need.
-
-The following settings are available in the settings file:
-
-| Name | Type | Description | Default |
-| ----------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
-| `Name` | `String` | Name of the module to publish. Defaults to the repository name. | `null` |
-| `ImportantFilePatterns` | `Array` | Regular expression patterns that identify important files. Changes matching these patterns trigger build, test, and publish stages. When set, fully replaces the defaults. | `['^src/', '^README\.md$']` |
-| `Test.Skip` | `Boolean` | Skip all tests | `false` |
-| `Test.Linux.Skip` | `Boolean` | Skip tests on Linux | `false` |
-| `Test.MacOS.Skip` | `Boolean` | Skip tests on macOS | `false` |
-| `Test.Windows.Skip` | `Boolean` | Skip tests on Windows | `false` |
-| `Test.SourceCode.Skip` | `Boolean` | Skip source code tests | `false` |
-| `Test.SourceCode.Linux.Skip` | `Boolean` | Skip source code tests on Linux | `false` |
-| `Test.SourceCode.MacOS.Skip` | `Boolean` | Skip source code tests on macOS | `false` |
-| `Test.SourceCode.Windows.Skip` | `Boolean` | Skip source code tests on Windows | `false` |
-| `Test.PSModule.Skip` | `Boolean` | Skip PSModule framework tests | `false` |
-| `Test.PSModule.Linux.Skip` | `Boolean` | Skip PSModule framework tests on Linux | `false` |
-| `Test.PSModule.MacOS.Skip` | `Boolean` | Skip PSModule framework tests on macOS | `false` |
-| `Test.PSModule.Windows.Skip` | `Boolean` | Skip PSModule framework tests on Windows | `false` |
-| `Test.Module.Skip` | `Boolean` | Skip module tests | `false` |
-| `Test.Module.Linux.Skip` | `Boolean` | Skip module tests on Linux | `false` |
-| `Test.Module.MacOS.Skip` | `Boolean` | Skip module tests on macOS | `false` |
-| `Test.Module.Windows.Skip` | `Boolean` | Skip module tests on Windows | `false` |
-| `Test.TestResults.Skip` | `Boolean` | Skip test result processing | `false` |
-| `Test.CodeCoverage.Skip` | `Boolean` | Skip code coverage tests | `false` |
-| `Test.CodeCoverage.PercentTarget` | `Integer` | Target code coverage percentage | `0` |
-| `Test.CodeCoverage.StepSummaryMode` | `String` | Step summary mode for code coverage reports | `'Missed, Files'` |
-| `Build.Skip` | `Boolean` | Skip all build tasks | `false` |
-| `Build.Module.Skip` | `Boolean` | Skip module build | `false` |
-| `Build.Docs.Skip` | `Boolean` | Skip documentation build | `false` |
-| `Build.Docs.ShowSummaryOnSuccess` | `Boolean` | Show super-linter summary on success for documentation linting | `false` |
-| `Build.Site.Skip` | `Boolean` | Skip site build | `false` |
-| `Publish.Module.Skip` | `Boolean` | Skip module publishing | `false` |
-| `Publish.Module.AutoCleanup` | `Boolean` | Automatically clean up old prerelease tags when merging to main or when a PR is abandoned | `true` |
-| `Publish.Module.AutoPatching` | `Boolean` | Automatically patch module version | `true` |
-| `Publish.Module.IncrementalPrerelease` | `Boolean` | Use incremental prerelease versioning | `true` |
-| `Publish.Module.DatePrereleaseFormat` | `String` | Format for date-based prerelease (uses [.NET DateTime format strings](https://learn.microsoft.com/dotnet/standard/base-types/standard-date-and-time-format-strings)) | `''` |
-| `Publish.Module.VersionPrefix` | `String` | Prefix for version tags | `'v'` |
-| `Publish.Module.MajorLabels` | `String` | Labels indicating a major version bump | `'major, breaking'` |
-| `Publish.Module.MinorLabels` | `String` | Labels indicating a minor version bump | `'minor, feature'` |
-| `Publish.Module.PatchLabels` | `String` | Labels indicating a patch version bump | `'patch, fix'` |
-| `Publish.Module.IgnoreLabels` | `String` | Labels indicating no release | `'NoRelease'` |
-| `Publish.Module.UsePRTitleAsReleaseName` | `Boolean` | Use the PR title as the GitHub release name instead of version string | `false` |
-| `Publish.Module.UsePRBodyAsReleaseNotes` | `Boolean` | Use the PR body as the release notes content | `true` |
-| `Publish.Module.UsePRTitleAsNotesHeading` | `Boolean` | Prepend PR title as H1 heading with PR number link before the body | `true` |
-| `Linter.Skip` | `Boolean` | Skip repository linting | `false` |
-| `Linter.ShowSummaryOnSuccess` | `Boolean` | Show super-linter summary on success for repository linting | `false` |
-| `Linter.env` | `Object` | Environment variables for super-linter configuration | `{}` |
-
-
-`PSModule.yml` with all defaults
-
-```yaml
-Name: null
-
-ImportantFilePatterns:
- - '^src/'
- - '^README\.md$'
-
-Build:
- Skip: false
- Module:
- Skip: false
- Docs:
- Skip: false
- ShowSummaryOnSuccess: false
- Site:
- Skip: false
-
-Test:
- Skip: false
- Linux:
- Skip: false
- MacOS:
- Skip: false
- Windows:
- Skip: false
- SourceCode:
- Skip: false
- Linux:
- Skip: false
- MacOS:
- Skip: false
- Windows:
- Skip: false
- PSModule:
- Skip: false
- Linux:
- Skip: false
- MacOS:
- Skip: false
- Windows:
- Skip: false
- Module:
- Skip: false
- Linux:
- Skip: false
- MacOS:
- Skip: false
- Windows:
- Skip: false
- TestResults:
- Skip: false
- CodeCoverage:
- Skip: false
- PercentTarget: 0
- StepSummaryMode: 'Missed, Files'
-
-Publish:
- Module:
- Skip: false
- AutoCleanup: true
- AutoPatching: true
- IncrementalPrerelease: true
- DatePrereleaseFormat: ''
- VersionPrefix: 'v'
- MajorLabels: 'major, breaking'
- MinorLabels: 'minor, feature'
- PatchLabels: 'patch, fix'
- IgnoreLabels: 'NoRelease'
- UsePRTitleAsReleaseName: false
- UsePRBodyAsReleaseNotes: true
- UsePRTitleAsNotesHeading: true
-
-Linter:
- Skip: false
- ShowSummaryOnSuccess: false
- env: {}
-```
-
-
-
-## Example 1 - Defaults with Code Coverage target
-
-This example runs all steps and will require that code coverage is 80% before passing.
-
-```yaml
-Test:
- CodeCoverage:
- PercentTarget: 80
-```
-
-## Example 2 - Rapid testing
-
-This example ends up running Plan, Build-Module and Test-Module (tests from the module repo) on **ubuntu-latest** only.
-
-```yaml
-Test:
- SourceCode:
- Skip: true
- PSModule:
- Skip: true
- Module:
- MacOS:
- Skip: true
- Windows:
- Skip: true
- TestResults:
- Skip: true
- CodeCoverage:
- Skip: true
-Build:
- Docs:
- Skip: true
-```
-
-## Example 3 - Configuring the Repository Linter
-
-The workflow uses [super-linter](https://github.com/super-linter/super-linter) to lint your repository code.
-The linter runs on pull requests and provides status updates directly in the PR.
-
-### Disabling the Linter
-
-You can skip repository linting entirely:
-
-```yaml
-Linter:
- Skip: true
-```
-
-### Configuring Linter Validation Rules
-
-The workflow supports all environment variables that **super-linter** provides. You can configure these through the `Linter.env` object:
-
-```yaml
-Linter:
- env:
- # Disable specific validations
- VALIDATE_BIOME_FORMAT: false
- VALIDATE_BIOME_LINT: false
- VALIDATE_GITHUB_ACTIONS_ZIZMOR: false
- VALIDATE_JSCPD: false
- VALIDATE_JSON_PRETTIER: false
- VALIDATE_MARKDOWN_PRETTIER: false
- VALIDATE_YAML_PRETTIER: false
-
- # Or enable only specific validations
- VALIDATE_YAML: true
- VALIDATE_JSON: true
- VALIDATE_MARKDOWN: true
-```
-
-### Additional Configuration
-
-Any super-linter environment variable can be set through the `Linter.env` object:
-
-```yaml
-Linter:
- env:
- LOG_LEVEL: DEBUG
- FILTER_REGEX_EXCLUDE: '.*test.*'
- VALIDATE_ALL_CODEBASE: false
-```
-
-### Showing Linter Summary on Success
-
-By default, the linter only shows a summary when it finds issues. You can enable summary display on successful runs:
-
-```yaml
-Linter:
- ShowSummaryOnSuccess: true
-```
-
-This is useful for reviewing what was checked even when no issues are found.
-
-**Note:** The `GITHUB_TOKEN` is automatically provided by the workflow to enable status updates in pull requests.
-
-For a complete list of available environment variables and configuration options, see the
-[super-linter environment variables documentation](https://github.com/super-linter/super-linter#environment-variables).
-
-## Example 4 - Configuring PR-based release notes
-
-The workflow can automatically generate GitHub release names and notes from your pull request content.
-Three parameters control this behavior:
-
-| Parameter | Description |
-|-----------|-------------|
-| `UsePRTitleAsReleaseName` | Use the PR title as the GitHub release name instead of the version string |
-| `UsePRBodyAsReleaseNotes` | Use the PR body as the release notes content |
-| `UsePRTitleAsNotesHeading` | Prepend PR title as H1 heading with PR number link before the body |
-
-These parameters follow specific precedence rules when building release notes:
-
-1. **Heading + Body** (`UsePRTitleAsNotesHeading: true` + `UsePRBodyAsReleaseNotes: true`): Creates formatted notes with the PR title as an H1 heading followed by the PR body. The output format is `# PR Title (#123)\n\nPR body content`. Both the PR title and body must be present.
-1. **Body only** (`UsePRBodyAsReleaseNotes: true`): Uses the PR body as-is for release notes. Takes effect when heading option is disabled or PR title is missing.
-1. **Fallback**: When neither option is enabled or required PR content is missing, GitHub's auto-generated release notes are used via `--generate-notes`.
-
-### Default configuration (recommended)
-
-The defaults provide rich release notes with the PR title as a heading:
-
-```yaml
-Publish:
- Module:
- UsePRTitleAsReleaseName: false
- UsePRBodyAsReleaseNotes: true
- UsePRTitleAsNotesHeading: true
-```
-
-This produces release notes like:
-
-```markdown
-# 🚀 Add new authentication feature (#42)
-
-This PR adds OAuth2 support with the following changes:
-- Added `Connect-OAuth2` function
-- Updated documentation
-```
-
-### Version-only release names
-
-If you prefer version numbers as release names but still want PR-based notes:
-
-```yaml
-Publish:
- Module:
- UsePRTitleAsReleaseName: false
- UsePRBodyAsReleaseNotes: true
- UsePRTitleAsNotesHeading: false
-```
-
-### Auto-generated notes
-
-To use GitHub's auto-generated release notes instead of PR content:
-
-```yaml
-Publish:
- Module:
- UsePRTitleAsReleaseName: false
- UsePRBodyAsReleaseNotes: false
- UsePRTitleAsNotesHeading: false
-```
diff --git a/src/docs/Capabilities/process-psmodule/design.md b/src/docs/Capabilities/process-psmodule/design.md
deleted file mode 100644
index cacf362..0000000
--- a/src/docs/Capabilities/process-psmodule/design.md
+++ /dev/null
@@ -1,218 +0,0 @@
----
-title: Design
-description: How Process-PSModule delivers the spec — a single reusable GitHub Actions workflow composing sub-workflows, a settings file contract, and the scenario matrix.
----
-
-# Process-PSModule — Design
-
-The behaviour in the [spec](spec.md) is delivered by a **single reusable GitHub Actions workflow** at `PSModule/Process-PSModule/.github/workflows/workflow.yml`. A repository using the workflow provides a caller workflow and a minimal `.github/PSModule.yml` settings file; everything else uses sensible defaults.
-
-## Workflow architecture
-
-### Single entry point
-
-The reusable workflow accepts a caller workflow and minimal caller configuration:
-
-```yaml
-# .github/workflows/Process-PSModule.yml in the module repository
-name: Process-PSModule
-
-on:
- workflow_dispatch:
- schedule:
- - cron: '0 0 * * *'
- pull_request:
- branches:
- - main
- types:
- - closed
- - opened
- - reopened
- - synchronize
- - labeled
-
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
-permissions:
- contents: write
- pull-requests: write
- statuses: write
- pages: write
- id-token: write
-
-jobs:
- Process-PSModule:
- uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
- secrets:
- APIKey: ${{ secrets.APIKey }}
-```
-
-### Composed reusable workflows
-
-The main workflow composes work across specialized reusable workflows, each owning a pipeline stage:
-
-- **Plan** — reads the settings file and event context, decides what runs, computes the next version
-- **Lint-Repository** — validates repository structure and configuration
-- **Build-Module** — compiles the module source and versions the manifest
-- **Test-SourceCode** — validates source-code style and standards (PSScriptAnalyzer, framework tests)
-- **Lint-SourceCode** — runs static analysis on source
-- **Test-Module** — runs framework tests and module-local Pester tests in parallel per platform
-- **Get-TestResults** — aggregates test results and enforces pass/fail
-- **Get-CodeCoverage** — collects coverage from tests and enforces thresholds
-- **Publish-Module** — publishes the module to the PowerShell Gallery
-- **Publish-Site** — generates and publishes documentation to GitHub Pages
-
-Each workflow is reusable so it can be tested and versioned independently, invoked by name in the main orchestration workflow.
-
-## Settings file contract
-
-The caller provides `.github/PSModule.yml`:
-
-```yaml
-# Minimal example — defaults apply for everything not specified
-Linter:
- Repository:
- Enabled: true
-
-Build:
- Module:
- Enabled: true
-
-Test:
- SourceCode:
- Enabled: true
- PSModule:
- Enabled: true
- Module:
- Enabled: true
- CodeCoverage:
- Enabled: true
- Threshold: 80
-
-Publish:
- Module:
- Enabled: true
- Site:
- Enabled: true
-```
-
-The Plan job reads this settings file, enriches it with computed values (phase enables, test matrices, resolved version, release decision), and passes the enriched settings to downstream jobs as a JSON string in workflow outputs.
-
-### Runtime settings contract
-
-| Path | Meaning |
-| --- | --- |
-| `Settings.Linter.Repository.Enabled` | Whether repository linting runs. |
-| `Settings.Build.Module.Enabled` | Whether module build runs. |
-| `Settings.Test.SourceCode.Enabled` | Whether source-code tests run. |
-| `Settings.Test.PSModule.Enabled` | Whether framework tests run. |
-| `Settings.Test.Module.Enabled` | Whether module-local tests run. |
-| `Settings.Test.TestResults.Enabled` | Whether test-results aggregation runs. |
-| `Settings.Test.CodeCoverage.Enabled` | Whether code-coverage gates run. |
-| `Settings.Publish.Module.Enabled` | Whether module publication runs. |
-| `Settings.Publish.Site.Enabled` | Whether documentation publication runs. |
-| `Settings.Test.SourceCode.Suites` | Computed source-code test matrix (platform × test suite). |
-| `Settings.Test.PSModule.Suites` | Computed framework test matrix (platform × test suite). |
-| `Settings.Test.Module.Suites` | Computed module-local test matrix (platform × test suite). |
-| `Settings.Publish.Module.Resolution.Version` | Resolved semantic version (e.g., `v1.2.3`). |
-| `Settings.Publish.Module.Resolution.Prerelease` | Whether the version is prerelease. |
-| `Settings.Publish.Module.Resolution.FullVersion` | Full version string (e.g., `v1.2.3-pr.1.5`). |
-| `Settings.Publish.Module.Resolution.ReleaseType` | `stable`, `prerelease`, or `none`. |
-| `Settings.Publish.Module.Resolution.CreateRelease` | Whether to create a GitHub Release. |
-
-## Scenario matrix
-
-### Version labeling
-
-- **Major** — breaking change; bump `MAJOR` in SemVer
-- **Minor** — new feature; bump `MINOR`
-- **Patch** — bugfix; bump `PATCH` (default if no label)
-- **Prerelease** — publish as prerelease, not promoted to latest
-- **NoRelease** — run pipeline, skip publication
-
-Multiple SemVer labels or conflicting labels (e.g., `Major` + `NoRelease`) are rejected and block the merge.
-
-### Branch types
-
-- **Main (stable)** — publishes stable releases. A prerelease label publishes a prerelease from `main`.
-- **Development** — optional prerelease branch (e.g., `dev`). Each push publishes a prerelease.
-- **Feature branch** — optional feature branch. A prerelease label publishes a prerelease for testing.
-
-### Platform matrix
-
-Tests run on:
-
-- **Windows** (latest)
-- **Linux** (Ubuntu latest)
-- **macOS** (latest)
-
-Failures on any platform block the build.
-
-### Test suites
-
-Each platform runs in parallel:
-
-- **Source-code tests** — style, naming, structure (PSModule framework)
-- **Framework tests** — module structure, common issues (PSModule framework)
-- **Module-local tests** — Pester tests written by the module author
-- **Linting** — PSScriptAnalyzer rules
-
-Test results are aggregated into a single pass/fail and reported to the PR.
-
-## Alternatives considered
-
-### Monolithic workflow vs. composable reusable workflows
-
-**Chosen: Composable reusable workflows**
-
-Each stage of the pipeline is a reusable workflow so it can be tested independently, versioned, and reused across the ecosystem. This trades orchestration complexity for testability and clarity.
-
-**Alternative: Single monolithic workflow**
-
-All logic in one workflow file. Pros: simpler to read end-to-end. Cons: harder to test, version, and reuse; changes in one stage risk all stages; every module repo copies the full logic.
-
-### Settings file format
-
-**Chosen: YAML with runtime enrichment**
-
-The caller provides a simple YAML file; the Plan job enriches it with computed values and passes the enriched settings to all downstream jobs. Pros: simple, readable, minimal to start. Cons: only the Plan job computes the settings; other jobs consume them.
-
-**Alternative: JSON in workflow outputs**
-
-Settings live only as workflow outputs, computed by Plan. Pros: single source of truth. Cons: harder to read and edit; no local file to inspect.
-
-### Version computation
-
-**Chosen: PR label + current version**
-
-The bump comes from the PR label; the next version is computed as `current_version + bump`. Pros: explicit, git-traceable (the label is recorded in the PR). Cons: must be re-computed if a PR is re-run or the base version changes.
-
-**Alternative: Conventional Commits**
-
-Parse commit messages for `feat:`, `fix:`, `BREAKING CHANGE:` to infer the bump. Pros: automatic. Cons: less explicit; easy to forget the convention; harder to override.
-
-## External dependencies
-
-The workflow relies on:
-
-- **[PSModule/Build-PSModule](https://github.com/PSModule/Build-PSModule)** — compiles and versions the module
-- **[PSModule/Test-PSModule](https://github.com/PSModule/Test-PSModule)** — runs framework tests and style validation
-- **[PSModule/Invoke-ScriptAnalyzer](https://github.com/PSModule/Invoke-ScriptAnalyzer)** — runs PSScriptAnalyzer linting
-- **[Pester](https://pester.dev/)** — runs module tests
-- **[GitHub Actions](https://github.com/features/actions)** — workflow engine
-- **PowerShell Gallery API** — publishes module packages
-- **GitHub Pages** — hosts documentation
-- **Zensical** — generates documentation from source
-
-Each is versioned independently; the main workflow pins versions explicitly.
-
-## Where this connects
-
-- [Spec](spec.md) — the requirements this design delivers.
-- [Pipeline stages](pipeline-stages.md) — detailed breakdown of each job.
-- [Usage](usage.md) — how to invoke and configure.
-- [Configuration](configuration.md) — the settings file reference.
-- [Principles and practices](principles-and-practices.md) — the principles guiding this design.
-- [Repository structure](repository-structure.md) — the repo layout the workflow expects.
diff --git a/src/docs/Capabilities/process-psmodule/index.md b/src/docs/Capabilities/process-psmodule/index.md
deleted file mode 100644
index d47451f..0000000
--- a/src/docs/Capabilities/process-psmodule/index.md
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: Process-PSModule
-description: The end-to-end PowerShell module pipeline — what it must guarantee and how it is built, alongside reference documentation for configuration and deployment.
----
-
-# Process-PSModule
-
-An end-to-end PowerShell module pipeline that automates the entire lifecycle of a module: building from source, running cross-platform tests, enforcing code quality and coverage, generating documentation, and publishing the versioned module to the PowerShell Gallery and its documentation site to GitHub Pages. It is the core workflow used across all PowerShell modules in the [PSModule organization](https://github.com/PSModule), ensuring reliable, automated, and maintainable delivery of PowerShell projects.
-
-
-
-| Page | Description |
-| --- | --- |
-| [Spec](spec.md) | Requirements for Process-PSModule — an end-to-end PowerShell module pipeline that guarantees build, testing, quality gates, documentation generation, and versioned publication to package and docs registries. |
-| [Design](design.md) | How Process-PSModule delivers the spec — a single reusable GitHub Actions workflow composing sub-workflows, a settings file contract, and the scenario matrix. |
-| [Pipeline stages](pipeline-stages.md) | The job-by-job breakdown of the Process-PSModule workflow, from Plan through Publish Docs. |
-| [Usage](usage.md) | How to call the Process-PSModule workflow — inputs, secrets, permissions, the scenario matrix, and important-file change detection. |
-| [Configuration](configuration.md) | The Process-PSModule settings file — every available setting, the full defaults, and worked examples for coverage, rapid testing, linting, and release notes. |
-| [Skipping framework tests](skipping-framework-tests.md) | How to skip individual PSModule framework tests on a per-file basis, the available test IDs, and the broader configuration alternatives. |
-| [Repository structure](repository-structure.md) | The repository and module source layout Process-PSModule expects, and how to declare module dependencies with #Requires -Modules. |
-| [Principles and practices](principles-and-practices.md) | The versioning, branching, and colocation principles behind Process-PSModule, and the development practices it is compatible with. |
-
-
-
-## How to get started
-
-1. [Create a repository from the Template-Module](https://github.com/new?template_name=Template-PSModule&template_owner=PSModule&description=Add%20a%20description%20(required)&name=%3CModule%20name%3E).
-2. Configure the repository:
- 1. Enable GitHub Pages in the repository settings. Set it to deploy from **GitHub Actions**.
- 2. This will create an environment called `github-pages` that GitHub deploys your site to.
- Within the github-pages environment, remove the branch protection for main.
- 
-
-Workflow suggestion
-
-```yaml
-name: Process-PSModule
-
-on:
- workflow_dispatch:
- schedule:
- - cron: '0 0 * * *'
- pull_request:
- branches:
- - main
- types:
- - closed
- - opened
- - reopened
- - synchronize
- - labeled
-
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
-permissions:
- contents: write
- pull-requests: write
- statuses: write
- pages: write
- id-token: write
-
-jobs:
- Process-PSModule:
- uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
- secrets:
- APIKey: ${{ secrets.APIKey }}
-```
-
-
-
-## Inputs
-
-| Name | Type | Description | Required | Default |
-| ---- | ---- | ----------- | -------- | ------- |
-| `SettingsPath` | `string` | The path to the settings file. All workflow configuration is controlled through this settings file. | `false` | `.github/PSModule.yml` |
-| `Debug` | `boolean` | Enable debug output. | `false` | `false` |
-| `Verbose` | `boolean` | Enable verbose output. | `false` | `false` |
-| `Version` | `string` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | `false` | `''` |
-| `Prerelease` | `boolean` | Whether to use a prerelease version of the 'GitHub' module. | `false` | `false` |
-| `WorkingDirectory` | `string` | The path to the root of the repo. | `false` | `'.'` |
-| `ImportantFilePatterns` | `string` | Newline-separated list of regular expression patterns that identify important files. Changes matching these patterns trigger build, test, and publish stages. When set, fully replaces the defaults. | `false` | `^src/\n^README\.md$` |
-
-## Secrets
-
-The reusable workflow at `.github/workflows/workflow.yml` declares only two workflow-call secrets,
-which keeps the calling workflow in full control of the credentials that are exposed.
-`secrets: inherit` is intentionally not required.
-
-| Name | Location | Description | Required |
-| ---- | -------- | ----------- | -------- |
-| `APIKey` | GitHub secrets | The API key for the PowerShell Gallery, used to publish the module. | Yes |
-| `TestData` | GitHub secrets | A single-line JSON object with `secrets` and `variables` maps, exposed as environment variables to the module test jobs. Values under `secrets` are masked; values under `variables` are not. | No |
-
-### Breaking change: fixed test secrets moved to `TestData`
-
-The reusable workflow no longer declares or accepts the old fixed test-secret inputs:
-
-- `TEST_APP_ENT_CLIENT_ID`
-- `TEST_APP_ENT_PRIVATE_KEY`
-- `TEST_APP_ORG_CLIENT_ID`
-- `TEST_APP_ORG_PRIVATE_KEY`
-- `TEST_USER_ORG_FG_PAT`
-- `TEST_USER_USER_FG_PAT`
-- `TEST_USER_PAT`
-
-If a caller passed any of these secrets directly, move them into the `secrets` map inside `TestData`.
-The environment variable names used by the tests can stay the same; only the workflow-call interface
-changes:
-
-```yaml
-jobs:
- Process-PSModule:
- uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
- secrets:
- APIKey: ${{ secrets.APIKey }}
- TestData: >-
- { "secrets": { "TEST_USER_PAT": "${{ secrets.TEST_USER_PAT }}",
- "TEST_APP_ORG_CLIENT_ID": "${{ secrets.TEST_APP_ORG_CLIENT_ID }}" } }
-```
-
-### Passing test phase data (secrets and variables)
-
-A single `TestData` secret lets a module expose any number of caller-defined values to its test jobs
-(`BeforeAll-ModuleLocal`, `Test-ModuleLocal` and `AfterAll-ModuleLocal`) without changing the shared
-workflow. It is one JSON object with two maps, so everything the tests need is visible in one place:
-
-```json
-{ "secrets": { "NAME": "value" }, "variables": { "NAME": "value" } }
-```
-
-Values under `secrets` are masked in the logs; values under `variables` are not. Build it in the
-calling workflow and pass it through the `secrets:` block (so the whole blob is masked). Reference each
-secret directly as `"${{ secrets. }}"` and each variable as `${{ toJSON(vars.) }}`. A
-folded `>-` scalar keeps the source readable while producing a single-line value, as long as the JSON
-content lines stay at the same indentation level:
-
-```yaml
-jobs:
- Process-PSModule:
- uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
- secrets:
- APIKey: ${{ secrets.APIKey }}
- TestData: >-
- { "secrets": { "CONFLUENCE_API_TOKEN": "${{ secrets.CONFLUENCE_API_TOKEN }}" },
- "variables": { "CONFLUENCE_SITE": ${{ toJSON(vars.CONFLUENCE_SITE) }},
- "CONFLUENCE_USERNAME": ${{ toJSON(vars.CONFLUENCE_USERNAME) }},
- "CONFLUENCE_SPACE_KEY": ${{ toJSON(vars.CONFLUENCE_SPACE_KEY) }} } }
-```
-
-Each entry becomes an environment variable in the test jobs, so the module's Pester tests read the
-values directly:
-
-```powershell
-$env:CONFLUENCE_API_TOKEN # from the "secrets" map (masked in logs)
-$env:CONFLUENCE_SITE # from the "variables" map (not masked)
-```
-
-The same `TestData` keys are exported before every module-local phase runs:
-
-- `BeforeAll-ModuleLocal` runs root `tests/BeforeAll.ps1` before the module-local test matrix.
-- `Test-ModuleLocal` discovers and runs module-local Pester tests recursively.
-- `AfterAll-ModuleLocal` runs root `tests/AfterAll.ps1` after the module-local test matrix, including cleanup paths.
-
-Setup and teardown detection is not recursive. These root scripts and the discovered tests should use the same environment variable names.
-If `$env:` is available in one phase but missing in another, treat that as a Process-PSModule
-propagation bug rather than a caller contract difference.
-
-Notes:
-
-- The names are caller-defined; no secret or variable names are hard-coded in the shared workflow.
- Names must match `^[A-Za-z_][A-Za-z0-9_]*$` and must not override reserved variables such as `PATH`,
- `CI`, `GITHUB_*`, `RUNNER_*` or `ACTIONS_*`.
-- The `TestData` validation, masking and environment export logic is shared by the ModuleLocal workflows
- through the [`PSModule/Install-PSModuleHelpers`](https://github.com/PSModule/Install-PSModuleHelpers)
- action, which installs the `Import-TestData` command each workflow runs to expose the values.
-- Reference secrets as `"${{ secrets. }}"` (quoted, directly) rather than
- `toJSON(secrets.)`. The direct form keeps CodeQL's *excessive secrets exposure* check happy and
- works for single-line secret values. It cannot carry values that contain `"`, `\` or newlines, so
- base64-encode a multi-line or special-character secret and decode it in the test (for example
- `[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($env:MY_KEY_B64))`).
-- Variables use `toJSON(vars.)` so any characters are JSON-encoded safely; they are never masked.
- You can use the same quoted direct form as secrets (`"${{ vars. }}"`) only for simple values
- that do not contain `"`, `\` or newlines.
-- Provide `TestData` as a single-line value (the folded `>-` block above does this). Avoid a literal
- `|` block: GitHub registers every line of a multi-line secret as its own mask, which over-masks
- unrelated log output.
-- Do not pretty-print `TestData` with nested indentation. YAML preserves more-indented lines inside a
- folded scalar, so a fully formatted JSON object can still become a multi-line secret. That makes
- GitHub register each line as its own mask, including brace-only lines such as `{`, `}` or `},`, which
- can turn unrelated log output into `***`. Keep the compact form above, or keep every JSON content
- line at the same indentation level.
-- Omit `TestData` entirely when the module needs no secrets or variables. Include only the map you
- need (just `secrets`, just `variables`, or both).
-- Because `secrets: inherit` is not used, only the values you list are ever exposed.
-- If using `secrets: inherit` in a caller workflow, remember that GitHub only forwards secrets that
- already exist by name. It does not assemble a `TestData` JSON payload from individual secrets such as
- `TEST_USER_PAT`; the caller must still create and pass the `TestData` value explicitly.
-- Organization, repository and GitHub *Environment* secrets and variables are supported when they are
- visible to the calling job. For environment-scoped values, set `environment:` on the calling job and
- explicitly include those values in `TestData`; they are not exposed automatically.
-
-## Permissions
-
-The following permissions are needed for the workflow to be able to perform all tasks.
-
-```yaml
-permissions:
- contents: write # to checkout the repo and create releases on the repo
- pull-requests: write # to write comments to PRs
- statuses: write # to update the status of the workflow from linter
- pages: write # to deploy to Pages
- id-token: write # to verify the Pages deployment originates from an appropriate source
-```
-
-For more info, see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site).
-
-## Scenario Matrix
-
-This table shows when each job runs based on the trigger scenario:
-
-| Job | Open/Updated PR | Merged PR | Abandoned PR | Manual Run |
-| ------------------------- | --------------- | ---------- | ------------ | ---------- |
-| **Plan** | ✅ Always | ✅ Always | ✅ Always | ✅ Always |
-| **Lint-Repository** | ✅ Yes | ❌ No | ❌ No | ❌ No |
-| **Build-Module** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Build-Docs** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Build-Site** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Test-SourceCode** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Lint-SourceCode** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Test-Module** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **BeforeAll-ModuleLocal** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Test-ModuleLocal** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **AfterAll-ModuleLocal** | ✅ Yes | ✅ Yes | ✅ Yes* | ✅ Yes |
-| **Get-TestResults** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Get-CodeCoverage** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
-| **Publish-Site** | ❌ No | ✅ Yes | ❌ No | ❌ No |
-| **Publish-Module** | ✅ Yes** | ✅ Yes** | ✅ Yes*** | ✅ Yes** |
-
-- \* Runs for cleanup if tests were started
-- \*\* Only when all tests/coverage/build succeed
-- \*\*\* Cleans up prerelease versions and tags created for the abandoned PR (when `Publish.Module.AutoCleanup` is
- enabled)
-
-## Important file change detection
-
-The workflow automatically detects whether a pull request contains changes to "important" files that should enter the
-build, test, and publish path. This prevents unnecessary work and releases when only files outside the configured
-patterns are modified.
-
-### Files that trigger the important-change path
-
-By default, the following regular expression patterns identify important files:
-
-| Pattern | Description |
-| :--- | :---------- |
-| `^src/` | Module source code |
-| `^README\.md$` | Module documentation |
-
-### Customizing important file patterns
-
-To override the default patterns, set `ImportantFilePatterns` in your settings file (`.github/PSModule.yml`):
-
-```yaml
-ImportantFilePatterns:
- - '^src/'
- - '^README\.md$'
- - '^tests/'
- - '^\.github/PSModule\.yml$'
- - '^\.github/workflows/'
-```
-
-When configured, the provided list fully replaces the defaults. Include the default patterns in your list if you still
-want them to trigger the build, test, and publish path.
-
-Recursive [module-local test discovery](pipeline-stages.md#module-local-test-discovery) does not change this trigger.
-With the defaults, a test-only change does not run the important-change build, test, and publish stages because
-`^tests/` is not matched. Add `^tests/` when those changes must exercise the path, plus each settings, workflow, or
-other automation path whose changes need the same validation. Include only paths that should trigger all three stages.
-
-To disable file-change triggering entirely (so that no file changes ever trigger a release), set an empty list in the
-settings file:
-
-```yaml
-ImportantFilePatterns: []
-```
-
-You can also pass patterns via the workflow input:
-
-```yaml
-jobs:
- Process:
- uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
- with:
- ImportantFilePatterns: |
- ^src/
- ^README\.md$
- ^examples/
-```
-
-To disable triggering via the workflow input, pass an explicit empty string:
-
-```yaml
-jobs:
- process:
- uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
- with:
- ImportantFilePatterns: ''
-```
-
-Note that omitting the `ImportantFilePatterns` key entirely causes the workflow's default patterns (`^src/` and
-`^README\.md$`) to be used. The settings file takes priority over the workflow input, so set
-`ImportantFilePatterns: []` in `.github/PSModule.yml` to disable triggering regardless of the workflow input.
-
-Resolution order: settings file → workflow input → workflow input default values.
-
-### Behavior when no important files are changed
-
-When a pull request does not contain changes to important files:
-
-1. A comment is automatically added to the PR listing the configured patterns and explaining why build/test stages are
- skipped
-2. `Settings.Publish.Module.Resolution.ReleaseType` is `None` (and `Settings.Publish.Module.Resolution.CreateRelease` is `false`)
-3. Build, test, and publish stages are skipped
-4. The PR can still be merged for non-release changes (documentation updates, CI improvements, etc.)
-
-This behavior ensures that maintenance PRs (such as updating GitHub Actions versions or fixing typos in comments)
-don't create unnecessary releases in the PowerShell Gallery.
diff --git a/src/docs/Coding-Standards/PowerShell/Testing.md b/src/docs/Coding-Standards/PowerShell/Testing.md
index fb20b6f..d50dfc2 100644
--- a/src/docs/Coding-Standards/PowerShell/Testing.md
+++ b/src/docs/Coding-Standards/PowerShell/Testing.md
@@ -55,4 +55,4 @@ tests/
└── Windows.Container.ps1
```
-Different directories may use different forms. Process-PSModule recursively applies its [per-directory discovery precedence](../../Capabilities/process-psmodule/pipeline-stages.md#module-local-test-discovery), including sibling suppression, unique test-name requirements, and root-only workflow phases.
+Different directories may use different forms. Process-PSModule recursively applies its [per-directory discovery precedence](https://psmodule.io/docs/Modules/Process-PSModule/), including sibling suppression, unique test-name requirements, and root-only workflow phases.
diff --git a/src/docs/Initiatives/PSModule.md b/src/docs/Initiatives/PSModule.md
index 04c06b1..1537f46 100644
--- a/src/docs/Initiatives/PSModule.md
+++ b/src/docs/Initiatives/PSModule.md
@@ -12,7 +12,7 @@ It is two things at once:
- **A module-building workflow** — GitHub Actions and reusable workflows that automate the whole PowerShell delivery lifecycle: build, test, version, and publish.
- **The modules themselves** — a growing collection of reusable PowerShell modules built with that workflow.
-PSModule inherits the [Coding Standards](../Coding-Standards/index.md) and [Ways of Working](../Ways-of-Working/index.md) from this site and adds only what is specific to the framework. The end-to-end workflow that ships every module — Process-PSModule — is documented under [Capabilities](../Capabilities/process-psmodule/index.md), and its module reference lives at [psmodule.io](https://psmodule.io).
+PSModule inherits the [Coding Standards](../Coding-Standards/index.md) and [Ways of Working](../Ways-of-Working/index.md) from this site and adds only what is specific to the framework. The end-to-end workflow that ships every module — [Process-PSModule](https://psmodule.io/docs/Modules/Process-PSModule/) — is documented at its canonical site.
## Canonical boundary
diff --git a/src/zensical.toml b/src/zensical.toml
index d068328..cd17916 100644
--- a/src/zensical.toml
+++ b/src/zensical.toml
@@ -148,17 +148,6 @@ nav = [
{"Spec" = "Capabilities/powershell-on-github/spec.md"},
{"Design" = "Capabilities/powershell-on-github/design.md"},
]},
- {"Process-PSModule" = [
- "Capabilities/process-psmodule/index.md",
- {"Spec" = "Capabilities/process-psmodule/spec.md"},
- {"Design" = "Capabilities/process-psmodule/design.md"},
- {"Pipeline Stages" = "Capabilities/process-psmodule/pipeline-stages.md"},
- {"Usage" = "Capabilities/process-psmodule/usage.md"},
- {"Configuration" = "Capabilities/process-psmodule/configuration.md"},
- {"Skipping Framework Tests" = "Capabilities/process-psmodule/skipping-framework-tests.md"},
- {"Repository Structure" = "Capabilities/process-psmodule/repository-structure.md"},
- {"Principles and Practices" = "Capabilities/process-psmodule/principles-and-practices.md"},
- ]},
{"Agentic Development" = [
"Capabilities/agentic-development/index.md",
{"Spec" = "Capabilities/agentic-development/spec.md"},