⚙️ [Maintenance]: Consolidation guidance and PSModule capability docs refreshed (#50)

This update advances the docs consolidation by adding a clear migration
plan and expanding the PSModule-related capability documentation so
contributors can align content ownership and publishing structure
consistently across repositories.

> ⚠️ This PR has no linked issue. Consider creating one for
traceability.

## Changed: Consolidation planning and capability documentation

A consolidation plan is now included to define canonical ownership and
migration direction between the docs repositories.

Capability documentation for PowerShell on GitHub has been added/updated
to clarify design, scope, and specification content used during
consolidation.

Initiative and capability index pages are updated so the new
consolidation direction is visible from top-level navigation.

## Technical Details

- Added `docs-consolidation-plan.md`.
- Added/updated capability docs under
`src/docs/Capabilities/powershell-on-github/` and capability index
links.
- Updated `src/docs/Initiatives/PSModule.md`.
- Updated formatting/config support files: `.prettierrc.json`,
`src/zensical.toml`, and `AGENTS.md`.

Author: MariusStorhaug

.prettierrc.json .github/linters/.prettierrc.json.prettierrc.json renamed to .github/linters/.prettierrc.json

@@ -1,30 +1,29 @@
 # Agents
 
-This repository is the central documentation for the MSX ecosystem. Everything an agent needs to work here — and the roles agents play across the ecosystem — is documentation, read the same way a new teammate would.
+## Main directive
 
-## Start here
+Everything is a work in progress and can be updated and improved.
+If you find a problem, fix it if it's small; otherwise, register it as an issue in the respective repo.
 
-1. Read this file, then the [README](README.md) for what this repository is and how it builds.
-2. Read the [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — how work flows from idea to delivery.
-3. Load the [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) relevant to the change.
+## Install the ecosystem
 
-## Roles
+1. Create a folder in the home directory called `.msx`:
+2. Clone the ecosystem locally:
+   1. <https://github.com/MSXOrg/docs> — requires PRs to be updated.
+      - Clone as bare and use worktrees.
+      - Create a worktree for all branches - worktree = name of the branch.
+   2. <https://github.com/MSXOrg/memory/> — work directly towards main.
+      - Simple clone, only main.
 
-Agent behaviour is authored once, as documentation, in the [Agents](https://msxorg.github.io/docs/Agents/) section. Use the role that fits the task:
+To install:
+- Clone the repos in the users home folder under a sub-folder named `.msx`.
+- Set configs locally to each of these repos using the GitHub username and email.
 
-- [Define](https://msxorg.github.io/docs/Agents/define/) — capture, refine, and plan a change into an issue.
-- [Implement](https://msxorg.github.io/docs/Agents/implement/) — deliver a planned issue as a review-ready pull request.
-- [Reviewer](https://msxorg.github.io/docs/Agents/reviewer/) — review a pull request for delivery, taste, and security.
-- [Security Reviewer](https://msxorg.github.io/docs/Agents/security-reviewer/) — a structured, defensive security pass.
-- [Agent Author](https://msxorg.github.io/docs/Agents/agent-author/) — create and maintain these roles and pointers.
+## Working with the ecosystem
 
-## How work happens here
-
-- [Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/) and [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/) — the branch model and where to work.
-- [Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/) — the draft-first, Copilot-review loop through to a ready pull request.
-- [Definition of Ready and Done](https://msxorg.github.io/docs/Ways-of-Working/Definition-of-Ready-and-Done/) — when a change is ready for review and when it lands.
-- This repository's build and checks — see the [README](README.md).
-
-## The rule
-
-This file points; it never defines. Process knowledge lives in the docs and is referenced by canonical URL — never copied here. See [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/).
+1. Get to know this repo first:
+   - [README](README.md) for what this repository is and how it builds.
+   - [CONTRIBUTING](CONTRIBUTING.md) for how to contribute and the review process.
+2. Read the `.msx/main/docs` - start with the index to get an overview of what is here.
+3. Read the `.msx/memory` - start with the index to get an overview of what is here. Use this while working - commit your memories here for work inside the PSModule organization.
+4. While working with the code, do small micro commits and push on every commit. This will make it easier to review and merge your changes.

AGENTS.md

@@ -21,6 +21,7 @@ and design relate and evolve.
 | [Merge Automation](merge-automation/index.md) | How a pull request's required status checks become the machine-readable signal that drives automated approval and merge — green merges, red holds, nothing bypasses the gate. |
 | [Downstream Release Propagation](downstream-release-propagation/index.md) | How a release in one repository propagates to the repositories that depend on it, via a delegated agent pull request. |
 | [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. |
 
 <!-- INDEX:END -->
 

src/docs/Capabilities/index.md

@@ -0,0 +1,42 @@
+---
+title: Design
+description: Architecture and implementation model for making GitHub PowerShell-native through modules, actions, and gap-closing workflows.
+---
+
+# Design
+
+## Capability model
+
+The model combines two tracks:
+
+- Build it: implement missing behavior using available GitHub and ecosystem APIs.
+- Advocate it: document and escalate platform-native features that require vendor support.
+
+## Architecture components
+
+1. Module collection
+   - reusable PowerShell modules grouped by domain (language helpers, data formats, networking, security, API clients)
+2. Automation collection
+   - reusable GitHub Actions for prepare, build, test, lint, document, publish, and release stages
+3. Orchestration framework
+   - Process-PSModule pipeline to drive module lifecycle and release behavior
+4. Parity gap backlog
+   - capability gaps mapped to either implementation or advocacy tracks
+
+## Operating pattern
+
+- Keep component-level details in initiative/module docs.
+- Keep reusable architecture and decision rationale here.
+- Link initiative pages to this capability as canonical context.
+
+## Current canonical references
+
+- PSModule initiative overview: ../../Initiatives/PSModule.md
+- Process-PSModule framework: ../../Frameworks/Process-PSModule/index.md
+- Coding standards baseline: ../../Coding-Standards/index.md
+
+## Planned evolution
+
+- Add a capability-level parity matrix with status per gap.
+- Track implementation maturity for each build-it stream.
+- Add explicit ownership and review cadence for advocacy items.

src/docs/Capabilities/powershell-on-github/design.md

@@ -0,0 +1,19 @@
+---
+title: PowerShell on GitHub
+description: How we make GitHub a first-class platform for PowerShell through reusable modules, actions, and capability gaps we close over time.
+---
+
+# PowerShell on GitHub
+
+This capability captures the strategic and technical work of infusing GitHub with PowerShell.
+
+It centralizes reusable architecture and platform-gap documentation previously spread across initiative-local docs.
+
+<!-- INDEX:START -->
+
+| Page | Description |
+| --- | --- |
+| [Spec](spec.md) | Requirements and boundaries for PowerShell parity on GitHub using reusable modules, actions, and platform advocacy. |
+| [Design](design.md) | Architecture and implementation model for making GitHub PowerShell-native through modules, actions, and gap-closing workflows. |
+
+<!-- INDEX:END -->

src/docs/Capabilities/powershell-on-github/index.md

@@ -0,0 +1,43 @@
+---
+title: Spec
+description: Requirements and boundaries for PowerShell parity on GitHub using reusable modules, actions, and platform advocacy.
+---
+
+# Spec
+
+## Problem
+
+GitHub offers strong language-native experiences for mainstream ecosystems, but PowerShell still has capability gaps in dependency intelligence, security signals, publishing ergonomics, and first-party tooling support.
+
+## Goal
+
+Provide a PowerShell-first GitHub development experience that is easy, fast, and safe by default.
+
+## Requirements
+
+1. Reusable automation should be packaged as versioned, SHA-pinnable actions and modules.
+2. Module and action delivery must be orchestrated through standardized CI/CD workflows.
+3. Missing platform support should be addressed through either:
+   - build-it paths (when APIs exist)
+   - advocacy paths (when only platform vendors can close the gap)
+4. Documentation for this capability must remain canonical in MSXOrg/docs.
+5. Initiative repositories can reference this capability but not fork its canonical guidance.
+
+## Scope
+
+In scope:
+
+- module and action architecture for PowerShell on GitHub
+- dependency, security, release, and publishing parity goals
+- implementation patterns and inventory-level framing
+
+Out of scope:
+
+- module-specific operational docs
+- repository-specific runbooks unrelated to reusable capability behavior
+
+## Success criteria
+
+- Capability guidance is discoverable under MSX capabilities.
+- Initiative-local copies are replaced with pointers.
+- PowerShell parity gaps are documented with a clear build-versus-advocate classification.

src/docs/Capabilities/powershell-on-github/spec.md

@@ -13,3 +13,13 @@ It is two things at once:
 - **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 [Frameworks](../Frameworks/Process-PSModule/index.md), and its module reference lives at [psmodule.io](https://psmodule.io).
+
+## Canonical boundary
+
+Cross-org standards and reusable architecture are canonical in MSXOrg/docs, including:
+
+- [Coding Standards](../Coding-Standards/index.md)
+- [Capabilities](../Capabilities/index.md)
+- [PowerShell on GitHub capability](../Capabilities/powershell-on-github/index.md)
+
+PSModule/docs is now intentionally scoped to module-specific operational details: module catalog pages, Process-PSModule repository anatomy, and template onboarding for module repositories.

src/docs/Initiatives/PSModule.md

@@ -1,29 +1,29 @@
 /* global document$, Tablesort */
 document$.subscribe(function () {
-    var tables = document.querySelectorAll("article table:not([class])");
-    tables.forEach(function (table) {
-        // If table doesn't have a thead, create one from the first row
-        if (!table.querySelector("thead")) {
-            var firstRow = table.querySelector("tr");
-            if (firstRow) {
-                var thead = document.createElement("thead");
-                thead.appendChild(firstRow);
-                table.insertBefore(thead, table.firstChild);
-            }
-        }
-        new Tablesort(table);
+  var tables = document.querySelectorAll("article table:not([class])");
+  tables.forEach(function (table) {
+    // If table doesn't have a thead, create one from the first row
+    if (!table.querySelector("thead")) {
+      var firstRow = table.querySelector("tr");
+      if (firstRow) {
+        var thead = document.createElement("thead");
+        thead.appendChild(firstRow);
+        table.insertBefore(thead, table.firstChild);
+      }
+    }
+    new Tablesort(table);
 
-        // Tablesort makes header cells focusable (tabindex=0) and sorts on click,
-        // but does not handle keyboard activation. Let Enter/Space sort too, so the
-        // sortable headers are usable without a mouse. Cover both th and td header
-        // cells, since a thead synthesized from the first row may hold td cells.
-        table.querySelectorAll("thead th, thead td").forEach(function (header) {
-            header.addEventListener("keydown", function (event) {
-                if (event.key === "Enter" || event.key === " ") {
-                    event.preventDefault();
-                    header.click();
-                }
-            });
-        });
+    // Tablesort makes header cells focusable (tabindex=0) and sorts on click,
+    // but does not handle keyboard activation. Let Enter/Space sort too, so the
+    // sortable headers are usable without a mouse. Cover both th and td header
+    // cells, since a thead synthesized from the first row may hold td cells.
+    table.querySelectorAll("thead th, thead td").forEach(function (header) {
+      header.addEventListener("keydown", function (event) {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          header.click();
+        }
+      });
     });
+  });
 });

src/overrides/assets/javascripts/tablesort.js

@@ -118,6 +118,11 @@ nav = [
       {"Spec" = "Capabilities/vscode-extension-framework/spec.md"},
       {"Design" = "Capabilities/vscode-extension-framework/design.md"},
     ]},
+    {"PowerShell on GitHub" = [
+      "Capabilities/powershell-on-github/index.md",
+      {"Spec" = "Capabilities/powershell-on-github/spec.md"},
+      {"Design" = "Capabilities/powershell-on-github/design.md"},
+    ]},
   ]},
   {"Frameworks" = [
     "Frameworks/index.md",