📖 [Docs]: Process-PSModule owns the documentation root (#452)

Process-PSModule documentation now lives at the root of the site. Its
lifecycle overview, getting-started material, guides, reference,
specifications, and media no longer sit beneath a
`Modules/Process-PSModule` source hierarchy.

## Changed: The framework owns the root page

The root page now uses the Process-PSModule title, description, and
lifecycle content as its primary documentation. It retains the
non-duplicated PSModule and cross-organization context from the former
root page, so readers land directly in the framework without losing the
broader context.

## Changed: Clear top-level documentation sections

The navigation now presents Process-PSModule, Getting started, Guides,
Reference, Specification, and Modules at the top level. Reference
combines the framework's operational contracts with its
module-development standards. Modules is the standalone index for
discovering the PSModule organization’s modules. Dictionary pages remain
published for inline glossary links without occupying a visible
navigation tab.

## Fixed: The module index generator follows the new structure

The scheduled documentation update now fills the Modules page and
publishes each generated module detail page below it. Catalog icons and
module links resolve from their new root-level locations, so the next
automated refresh updates the visible module index instead of the
retired Catalog path.

---
<details>
<summary>Technical details</summary>

- Implementation plan progress: all steps in the scoped Task are
complete.
- Moved `get-started/`, `guides/`, `reference/`, `specification/`, and
`media/` with `git mv`, preserving file history.
- Merged the former inner landing page into `docs/content/index.md`; its
front matter, title, and framework content take precedence, while the
non-duplicated root content remains below it.
- Moved the module-development standards into `docs/content/reference/`
and added them to the top-level Reference navigation.
- Replaced the Catalog navigation entry with Modules, whose top-level
page is the module index.
- `Update-ModuleList` now writes generated pages to
`docs/content/Modules/Repositories/` and replaces the marker in
`docs/content/Modules/index.md`; the V2 catalog template references
assets at the correct depth.
- Added an isolated Pester regression test for the catalog generator and
installed its declared GitHub module dependency in the action test
workflow.
- Dictionary remains in Zensical's navigation graph because unlisted
pages are not built; a scoped stylesheet hides its tab and drawer
entries while preserving published glossary URLs.
- The strict clean Zensical build succeeds, the catalog Pester suite
passes, PSScriptAnalyzer reports no findings, and all in-repository
Markdown links resolve.
- Standards and framework alignment:

| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `docs/content/**` | Documentation Model | Process-PSModule information
architecture | Aligned |
| `docs/zensical.toml` | Documentation navigation | Zensical navigation
indexes | Aligned |
| `.github/actions/update-index/**` | PowerShell testing and action
conventions | Generated module catalog contract | Aligned |
| `AGENTS.md` | Agentic Development | Canonical framework guidance |
Aligned |

- Issue convergence sweep: reviewed the parent PBI and its current
delivery leaves; this pull request implements only the scoped
documentation-navigation Task.

</details>

<details>
<summary>Relevant issues (or links)</summary>

- Fixes #451
- #423

</details>

---------

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

Author: MariusStorhaug

.github/actions/update-index/src/Helper.psm1

@@ -831,7 +831,7 @@ function Update-ModuleList {
     $moduleRepos = $Repos | Where-Object {
         $_.Type -eq 'Module' -and $_.Owner -eq 'PSModule'
     } | Sort-Object Name
-    $catalogFolderPath = Join-Path 'docs\content\Modules\Catalog' 'Repositories'
+    $catalogFolderPath = Join-Path 'docs\content\Modules' 'Repositories'
     if (-not (Test-Path $catalogFolderPath)) {
         Write-Host "Creating catalog folder [$catalogFolderPath]"
         $null = New-Item -Path $catalogFolderPath -ItemType Directory
@@ -921,7 +921,7 @@ function Update-ModuleList {
 
     LogGroup 'Write module catalog table to docs index' {
         $moduleTable = $moduleCatalogTableTemplate.Replace('{{ ROWS }}', $moduleTableRows.TrimEnd())
-        Update-MDSection -Path '.\docs\content\Modules\Catalog\index.md' -Name 'MODULE_CATALOG' -Content $moduleTable
+        Update-MDSection -Path '.\docs\content\Modules\index.md' -Name 'MODULE_CATALOG' -Content $moduleTable
         Write-Host 'Module catalog table update completed'
     }
 }

.github/actions/update-index/templates/module-catalog/v2-table.html

@@ -3,10 +3,10 @@
 <table>
     <tr>
         <th width="24%">Name</th>
-        <th width="12%"><img src="../../assets/images/module-catalog/githubtags.svg" alt="Version" title="Version" width="16" height="16"></th>
-        <th width="24%"><img src="../../assets/images/module-catalog/package-variant-closed-check.svg" alt="Process version" title="Process version" width="16" height="16"></th>
-        <th width="10%"><img src="../../assets/images/module-catalog/githubissues.svg" alt="Issues" title="Issues" width="16" height="16"></th>
-        <th width="10%"><img src="../../assets/images/module-catalog/githubpullrequests.svg" alt="Pull requests" title="Pull requests" width="16" height="16"></th>
-        <th width="10%"><img src="../../assets/images/module-catalog/githubstars.svg" alt="Stars" title="Stars" width="16" height="16"></th>
+        <th width="12%"><img src="../assets/images/module-catalog/githubtags.svg" alt="Version" title="Version" width="16" height="16"></th>
+        <th width="24%"><img src="../assets/images/module-catalog/package-variant-closed-check.svg" alt="Process version" title="Process version" width="16" height="16"></th>
+        <th width="10%"><img src="../assets/images/module-catalog/githubissues.svg" alt="Issues" title="Issues" width="16" height="16"></th>
+        <th width="10%"><img src="../assets/images/module-catalog/githubpullrequests.svg" alt="Pull requests" title="Pull requests" width="16" height="16"></th>
+        <th width="10%"><img src="../assets/images/module-catalog/githubstars.svg" alt="Stars" title="Stars" width="16" height="16"></th>
     </tr>
 {{ ROWS }}</table>

.github/actions/update-index/tests/Update-Index.Helpers.Tests.ps1

@@ -0,0 +1,59 @@
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseDeclaredVarsMoreThanAssignments',
+    '',
+    Justification = 'The temporary path is assigned before assertions and cleanup.'
+)]
+[CmdletBinding()]
+param()
+
+BeforeAll {
+    Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../src/Helper.psm1') -Force
+}
+
+Describe 'Update-ModuleList' {
+    Context 'catalog page at the Modules root' {
+        It 'Update-ModuleList - writes the catalog index and repository page to the new Modules paths' {
+            $testRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("update-index-test-$([guid]::NewGuid())")
+            $modulesPath = Join-Path $testRoot 'docs/content/Modules'
+            $catalogIndexPath = Join-Path $modulesPath 'index.md'
+            New-Item -ItemType Directory -Path $modulesPath -Force | Out-Null
+            Set-Content -Path $catalogIndexPath -Value @(
+                '# Modules'
+                ''
+                '<!-- MODULE_CATALOG_START -->'
+                '<!-- MODULE_CATALOG_END -->'
+            )
+
+            try {
+                Push-Location $testRoot
+                InModuleScope Helper {
+                    Mock Get-RepositoryVersion { '1.2.3' }
+                    Mock Get-RepositoryReadmeContent { '# Example`nExample module summary.' }
+                    Mock Get-MarkdownSummary { 'Example module summary.' }
+                    Mock Get-WorkflowReference { 'v1.2.3' }
+                    Mock Get-ProcessReferenceStatus { 'up-to-date' }
+                    Mock Get-OpenItemCount { 0 }
+
+                    Update-ModuleList -Repos @(
+                        [pscustomobject]@{
+                            Type          = 'Module'
+                            Owner         = 'PSModule'
+                            Name          = 'Example'
+                            Description   = 'Example module.'
+                            DefaultBranch = 'main'
+                            Stars         = 1
+                        }
+                    )
+                }
+
+                $catalogContent = Get-Content -Path $catalogIndexPath -Raw
+                Test-Path (Join-Path $modulesPath 'Repositories/Example.md') | Should -BeTrue
+                $catalogContent | Should -Match '\./Repositories/Example\.md'
+                $catalogContent | Should -Match '\.\./assets/images/module-catalog/githubtags\.svg'
+            } finally {
+                Pop-Location
+                Remove-Item -LiteralPath $testRoot -Recurse -Force -ErrorAction SilentlyContinue
+            }
+        }
+    }
+}

.github/workflows/Test-Actions.yml

@@ -36,6 +36,7 @@ jobs:
         run: |
           Install-PSResource -Name Pester -Version '[5.7.1,6.0.0)' -Repository PSGallery -TrustRepository
           Install-PSResource -Name PSSemVer -Repository PSGallery -TrustRepository
+          Install-PSResource -Name GitHub -Version '[0.43.1,0.44.0)' -Repository PSGallery -TrustRepository
 
       - name: Run action unit tests
         shell: pwsh

AGENTS.md

@@ -15,7 +15,7 @@ If you find a problem or improvement, fix if small; otherwise open an issue.
 Regarding repo structure, module source code, and how the Process-PSModule workflow
 works. For PSModule-specific build, layout, and process guidance:
 
-- [Process-PSModule docs](https://psmodule.github.io/docs/Modules/Process-PSModule/) —
+- [Process-PSModule docs](https://psmodule.io/docs/) —
   repository structure, module anatomy, and the build/test/pack/publish pipeline.
 - [Repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) —
   the expected repository layout and required files.
@@ -28,11 +28,11 @@ works. For PSModule-specific build, layout, and process guidance:
 
 For cross-cutting ways of working and standards:
 
-- [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/) —
+- [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) —
   how agents and humans collaborate in this ecosystem.
-- [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — contribution
+- [Ways of Working](https://msx.no/docs/Ways-of-Working/) — contribution
   workflow, branching, PRs, issues.
-- [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) — language-level
+- [Coding Standards](https://msx.no/docs/Coding-Standards/) — language-level
   conventions.
 - [MSXOrg/memory](https://github.com/MSXOrg/memory) — durable agent working memory:
   gotchas, knowledge, and agent role notes.

docs/content/Modules/Catalog/index.md

@@ -1,19 +1,23 @@
 # Modules
 
-Process-PSModule now hosts PSModule-org module documentation.
+This page indexes modules maintained in the PSModule organization and what each module does.
 
-This section is the local source of truth for:
+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.
 
-- module catalog and module-level specs
-- Process-PSModule structure and build flow
-- repository anatomy and template onboarding
+## Scope
 
-## Sections
+Each module page should capture:
 
-- [Repository Standard](Repository-Standard.md)
-- [Standards](Standards.md)
-- [Module types](Module-Types.md)
-- [Test Specification](Test-Specification.md)
-- [Versioning](Versioning.md)
-- [Catalog](Catalog/index.md) (auto-generated from PSModule repo metadata, release data, and README summaries)
-- [Process-PSModule](Process-PSModule/index.md)
+- 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/Process-PSModule/index.md

@@ -34,4 +34,4 @@ If the module needs several interdependent commands before it is usable at all,
 | [Your first release](your-first-release.md) | The pull request flow, version labels, and what happens on merge. |
 | [Module bootstrap](module-bootstrap.md) | Getting a brand-new module to its first release with an integration branch. |
 
-For framework-level practices, refer to [MSX Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/).
+For framework-level practices, refer to [MSX Ways of Working](https://msx.no/docs/Ways-of-Working/).

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](../../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.
@@ -19,13 +19,13 @@ Scope the integration branch to exactly that core, not to everything planned for
 ## Pattern
 
 1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-thing-module`.
-2. Open one pull request per function (or small group of related functions) targeting that branch instead of `main`. These PRs can land in parallel — there is no strict order between them, unlike a [stacked pull request](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests).
+2. Open one pull request per function (or small group of related functions) targeting that branch instead of `main`. These PRs can land in parallel — there is no strict order between them, unlike a [stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests).
 3. Once the load-bearing core is coherent and complete, open the pull request that merges the integration branch into `main`. This becomes the module's first real release (`v1.0.0`).
 4. Smaller follow-up features (one more function, a formatter, an alias) can keep targeting the integration branch before it lands, the same way they targeted it during bootstrap.
 
 ## After the core lands
 
-Once the core has merged as `v1.0.0`, ordinary [SemVer](../../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
@@ -60,6 +60,6 @@ A module bootstrapped this way:
 ## When to use this
 
 - The module has no usable release yet, and the load-bearing core hasn't landed.
-- Use this only for the initial bootstrap. Once `main` has a first release, ongoing feature work targets `main` directly with ordinary topic branches, or a [stacked pull request](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests) when changes genuinely depend on each other.
+- Use this only for the initial bootstrap. Once `main` has a first release, ongoing feature work targets `main` directly with ordinary topic branches, or a [stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests) when changes genuinely depend on each other.
 
-For the general branching and merge model, see [MSX Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/).
+For the general branching and merge model, see [MSX Branching and Merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/).