Constrain documentation migration guidance to supported builds

Keep consumer documentation changes within the current site staging contract and surface unsupported authored-content migrations as framework gaps.

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

Author: MariusStorhaug

.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md

@@ -40,10 +40,9 @@ what is present before deciding what to migrate:
   workflow extensions. Keep them in separate files and validate them in place.
 
 When documentation is absent, do not invent a site as part of the caller
-upgrade unless the requested scope explicitly includes documentation migration.
-When a legacy MkDocs configuration exists and documentation migration is in
-scope, migrate its content and design deliberately to Zensical, then remove
-the obsolete configuration only after the generated site validates.
+upgrade. When a legacy MkDocs configuration exists, preserve it during the
+caller upgrade. A documentation migration that needs consumer-authored content
+or theme assets requires framework staging support before it can be delivered.
 
 ## Template-PSModule baseline
 
@@ -125,20 +124,10 @@ Treat files and directories as follows:
   Preserve the consumer's local onboarding contract while updating stale links.
 
 If the template revision and the consumer's existing layout disagree, record
-the difference and migrate only the requested integration surface. In
-particular, the current template uses `.github/zensical.toml`, while this v8
-upgrade request uses `docs/zensical.toml`, `docs/content/`, and
-`docs/overrides/` (including `docs/overrides/assets/`) as its documentation
-contract; a separate `docs/assets/` directory is optional. When that requested
-documentation migration is in scope, move the template's Zensical settings
-and custom assets into the `docs/` contract rather than maintaining both
-configurations. When it is not in scope, preserve the consumer's existing
-working configuration and report the difference.
-
-For a documentation-only MkDocs migration, use the dedicated
-[`psmodule-zensical-migration`](../psmodule-zensical-migration/SKILL.md) skill
-so content, theme, assets, and link validation are handled independently from
-the caller workflow upgrade.
+the difference and migrate only the requested integration surface. The
+template's `.github/zensical.toml` is the supported Process-PSModule consumer
+configuration. Do not move its site configuration, content, or theme assets
+into `docs/` as part of a v8 upgrade.
 
 ## Caller workflow contract
 
@@ -165,8 +154,6 @@ on:
       - labeled
       - unlabeled
 
-permissions: {}
-
 jobs:
   Process-PSModule-Production:
     if: ${{ github.event_name != 'pull_request' }}
@@ -241,24 +228,12 @@ uses.
 
 ## Documentation integration
 
-Treat `docs/zensical.toml` as authoritative. Do not create or maintain
-`mkdocs.yml`, introduce MkDocs configuration, or replace the consumer's
-documentation design with a parallel theme.
-
-Compare the consumer's configuration with the Process-PSModule template and
-preserve or migrate these surfaces deliberately:
-
-- `docs/zensical.toml`, including `docs_dir` and navigation.
-- `docs/content/` as the documentation source directory.
-- `docs/overrides/` and custom templates.
-- `docs/overrides/assets/stylesheets/navigation.css`.
-- `docs/overrides/assets/`, any optional `docs/assets/`, logo, favicon, palette,
-  fonts, and custom JavaScript/CSS.
-- Existing navigation labels, page paths, and custom theme behavior.
-
-Do not delete existing custom CSS/assets merely because the default theme also
-provides an equivalent feature. Resolve duplicate configuration in favor of
-the existing consumer source of truth, then validate the generated site.
+The v8 upgrade does not migrate documentation. Preserve the consumer's
+existing documentation source, custom assets, and active site configuration.
+For the Process-PSModule site build, keep the template's
+`.github/zensical.toml` configuration. Do not create `docs/zensical.toml` or
+move documentation content or theme assets into `docs/`; the module site build
+does not stage that contract.
 
 ## Pester v6 migration
 
@@ -310,15 +285,7 @@ when a targeted check reveals a broader dependency:
    equivalent when available.
 3. Run the Pester v6 test suites with the repository's declared configuration.
 4. Run the repository's existing lint and test commands.
-5. When documentation exists, run:
-
-   ```powershell
-   Push-Location docs
-   zensical build --clean
-   Pop-Location
-   ```
-
-6. Review the diff for accidental workflow permissions, trigger changes,
+5. Review the diff for accidental workflow permissions, trigger changes,
    secret exposure, fixture removal, generated files, or unrelated refactoring.
 
 Report commands and outcomes, including blocked checks and why they were

.github/plugin/psmodule/skills/psmodule-zensical-migration/SKILL.md

@@ -1,159 +1,64 @@
 ---
 name: psmodule-zensical-migration
-description: Migrate a PSModule repository from MkDocs to Zensical using the Process-PSModule documentation design as the default while preserving content, navigation, assets, and repository-specific behavior.
+description: Assess a PSModule repository's documentation migration to Zensical without introducing a site layout the Process-PSModule pipeline cannot publish.
 ---
 
-# Migrate PSModule documentation from MkDocs to Zensical
+# Assess a PSModule Zensical migration
 
-Use this skill when a PSModule repository has a legacy MkDocs configuration,
-usually `.github/mkdocs.yml`, or needs its documentation site aligned with the
-Process-PSModule Zensical design. Keep the migration limited to documentation
-integration. Do not rewrite module code or tests unless a documentation build
-requires a directly related fix.
+Use this skill when a PSModule repository has a legacy MkDocs configuration or
+needs its documentation site aligned with Zensical. Keep the assessment limited
+to documentation integration. Do not rewrite module code or tests unless a
+documentation build requires a directly related fix.
 
-## Source-of-truth design
+## Current Process-PSModule boundary
 
-Use the current
-[`Process-PSModule` `docs/zensical.toml`](https://github.com/PSModule/Process-PSModule/blob/main/docs/zensical.toml)
-as the default style and configuration baseline. Reuse its behavior rather than
-inventing a second theme:
+The module site pipeline stages generated function documentation, `README.md`,
+the module icon, and `.github/zensical.toml` into `outputs/site`. It does not
+stage consumer-authored `docs/content/`, `docs/overrides/`, or their assets.
+Consequently, a consumer configuration that sets `docs_dir = "content"` or
+`custom_dir = "overrides"` cannot be published through the current framework.
 
-- `docs_dir = "content"` with content under `docs/content/`.
-- `docs/overrides/` as the custom theme directory.
-- `docs/overrides/assets/stylesheets/navigation.css` for navigation styling.
-- `docs/overrides/assets/` and any repository-owned `docs/assets/` directory
-  when present as the asset source of truth.
-- Mona Sans text and Source Code Pro code fonts.
-- Material-style GitHub/link icons, light/dark/system palette toggles,
-  black/slate/light-blue colors, and the established navigation features.
-- Instant navigation, prefetch/preview/progress, tabs, tracking, top navigation,
-  search, code copy, tooltips, table of contents, and footer behavior.
-- TOC, attribute lists, abbreviations, admonitions, definition lists,
-  footnotes, tables, HTML-in-Markdown, details, superfences, task lists, and
-  snippets extensions.
-- Mermaid fenced blocks and the shared abbreviations snippet.
-- Existing social links, consent configuration, site metadata, edit URI, and
-  custom tablesort JavaScript where those features apply.
+Do not move a module consumer from `.github/zensical.toml` to
+`docs/zensical.toml`, or prescribe the Process-PSModule repository's
+`docs/content/` design, until the framework stages those paths.
 
-Customize only repository identity and content-specific values such as
-`site_name`, `site_url`, `repo_name`, `repo_url`, `edit_uri`, copyright, social
-links, and `nav`. Do not remove a default feature merely because the old
-MkDocs site did not use it.
+## Assess before changing
 
-## Inspect before changing
+1. Read local guidance, the current documentation build command, and the
+   Process-PSModule caller workflow.
+2. Inventory `.github/mkdocs.yml`, `mkdocs.yml`, `.github/zensical.toml`, and
+   any existing documentation sources, templates, media, and assets.
+3. Identify whether documentation is published by Process-PSModule or by a
+   separate repository-owned workflow.
+4. Preserve module source, generated help, custom assets, navigation, and
+   repository-owned workflows unless the requested migration requires them.
 
-Inventory the existing repository and record:
+## Supported consumer configuration
 
-1. Local guidance, branch state, and documentation build commands.
-2. `.github/mkdocs.yml`, any `mkdocs.yml`, and any existing Zensical config.
-3. The Markdown content root, includes/snippets, templates, media, and assets.
-4. `theme`, `theme.custom_dir`, `extra_css`, `extra_javascript`, `plugins`,
-   `markdown_extensions`, `nav`, `extra`, and `watch` settings.
-5. Links, anchors, generated API/help pages, redirects, and CI publishing steps.
-6. Existing custom CSS, JavaScript, templates, logos, favicons, and fonts.
+For a Process-PSModule consumer, retain the template's
+`.github/zensical.toml` configuration and the generated site layout. Do not
+add a second active site configuration.
 
-Do not assume every consumer has a `docs/` tree. If documentation is absent,
-create it only when the requested scope includes documentation migration. If
-the repository already uses Zensical, compare it with the Process-PSModule
-baseline and make only the required alignment changes.
-
-## Target layout
-
-For the Process-PSModule documentation contract, use:
-
-```text
-docs/
-├── content/
-├── overrides/
-│   └── assets/
-│       ├── javascripts/
-│       └── stylesheets/
-└── zensical.toml
-```
-
-Keep existing content under `docs/content/`, custom templates under
-`docs/overrides/`, and theme assets under `docs/overrides/assets/`. A separate
-`docs/assets/` directory is optional for static content assets. Do not create a
-parallel MkDocs theme or leave two active site configurations.
-
-The current `PSModule/Template-PSModule` repository historically stores a
-starter `.github/zensical.toml` and may not contain a `docs/` tree. When the
-consumer upgrade explicitly requires the Process-PSModule `docs/` contract,
-move the template settings and custom assets into `docs/` and remove the
-obsolete active configuration only after the site builds. When that contract
-is not in scope, preserve a working template layout and report the difference
-instead of moving files speculatively.
-
-## MkDocs-to-Zensical mapping
-
-Translate behavior, not just filenames:
-
-| MkDocs | Zensical |
-| --- | --- |
-| `site_name`, `site_url` | `[project]` metadata |
-| `docs_dir` | `[project].docs_dir` |
-| `repo_name`, `repo_url`, `edit_uri` | `[project]` metadata |
-| `nav` | `nav = [...]` TOML entries |
-| `theme.name` | `[project.theme]` settings |
-| `theme.custom_dir` | `[project.theme].custom_dir` |
-| `theme.logo`, `theme.favicon` | `[project.theme]` paths |
-| `theme.features` | `[project.theme].features` |
-| `theme.palette` | `[[project.theme.palette]]` tables |
-| `extra_css`, `extra_javascript` | `[project]` arrays |
-| `markdown_extensions` | `[project.markdown_extensions.*]` tables |
-| `plugins: search` | `[project.plugins.search]` |
-| `extra.social` | `[[project.extra.social]]` |
-| `watch` | `[project].watch` |
-
-Preserve Markdown semantics while checking extensions that affect formatting:
-admonitions, fenced code, tables, task lists, definition lists, attributes,
-snippets, Mermaid, and anchor/permalink behavior. Fix only documented
-Zensical incompatibilities; do not silently change headings or links to hide
-build failures.
-
-## Content and link migration
-
-- Preserve page paths and navigation labels where possible.
-- Keep explicit `nav` entries for important landing pages and references.
-- Resolve relative links from the new `docs/content/` root.
-- Recheck fragment anchors because heading and permalink behavior can differ.
-- Move includes/snippets to the configured Zensical location and update every
-  reference.
-- Keep generated API/help inputs in their framework-owned locations.
-- Preserve images and downloads; update paths rather than deleting assets.
-- Keep custom templates only when they are still required by the migrated site.
+When a requested migration needs authored Markdown content or a custom theme,
+record that the framework must first stage those assets into `outputs/site`.
+Do not claim the migration is complete until the producer supports the target
+layout and a consumer build publishes it successfully.
 
 ## Validation
 
-Run repository-native checks and the smallest targeted site checks first:
-
-1. Parse the new `docs/zensical.toml` and verify all configured paths exist.
-2. Confirm no active `mkdocs.yml` or MkDocs workflow remains.
-3. Check every navigation target, image, download, include, and fragment link.
-4. Run the existing documentation lint and link checks.
-5. Build the site:
-
-   ```powershell
-   Push-Location docs
-   zensical build --clean
-   Pop-Location
-   ```
-
-6. Review the generated site for navigation, search, palette toggles, fonts,
-   logo/favicon, custom navigation behavior, code blocks, Mermaid, and social
-   links.
-7. Run the repository's existing Process-PSModule workflow validation when the
-   documentation is part of that pipeline.
+1. Confirm the caller references the intended Process-PSModule version and
+   retains `.github/zensical.toml`.
+2. Run the consumer's existing documentation and Process-PSModule validation
+   commands when available.
+3. Review the generated site to confirm generated function documentation,
+   `README.md`, and module assets remain present.
 
-Do not claim success if the site builds while links, assets, navigation, or
-publishing behavior are broken. Report intentionally deferred pages,
-unsupported extensions, and unrelated pre-existing failures.
+Report any unsupported authored-content or custom-theme requirement as a
+framework gap rather than working around it with a second active
+configuration.
 
 ## References
 
-- [Process-PSModule Zensical configuration](https://github.com/PSModule/Process-PSModule/blob/main/docs/zensical.toml)
-- [Process-PSModule documentation overrides](https://github.com/PSModule/Process-PSModule/tree/main/docs/overrides)
-- [Process-PSModule override assets](https://github.com/PSModule/Process-PSModule/tree/main/docs/overrides/assets)
 - [PSModule repository standard](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/repository-standard.md)
-- [PSModule documentation model](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/guides/structuring-your-module.md)
+- [PSModule workflow inputs](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/workflow-inputs.md)
 - [Zensical setup basics](https://zensical.org/docs/setup/basics/)