Standardize module README + repository, agent, and module-type defaults by MariusStorhaug · Pull Request #61 · PSModule/docs

Marius Storhaug (MariusStorhaug) · 2026-07-09T04:16:30Z

What

Updates the module README default in PowerShell/Modules/Repository-Defaults.md so that standardizing a README does not delete unique information.

The README is published as the module's landing page on the docs site, for example psmodule.io/<ModuleName>. The per-command reference is generated separately from comment-based help. That means the README is often the only published home for prerequisites, platform and dependency notes, authentication and setup guidance, operational behavior such as caching, state, update and versioning, and upstream attribution. Deleting that content to shorten the README removes it from the site entirely.

Changes to the standard

Content preservation: keep, trim, or relocate, but never drop. Preserve unique content and remove only what is genuinely duplicated by the generated command reference.
Publishing model made explicit: the README publishes as the landing page. Content may move out of the README only into another published home, either a command group overview under src/functions/public/<Group>/<Group>.md or comment-based help. A bare top-level docs/ folder is not published, so moving content there drops it from the site. A longer README is acceptable for feature-rich modules.
Capabilities showcase is mandatory for implemented modules.
Upstream attribution exception: credit, acknowledgements, donation notes, and third-party license notices are retained.
README validation extended: fixes the copy/paste-hostile help example and tightens the validation checks.

Gauge

Applied on two content-rich repositories so the resulting READMEs can be used to judge the definition:

PSModule/NerdFonts#85 keeps the full README, including prerequisites, attribution, usage, caching, update semantics, and uninstall guidance, and adds a documentation pointer.
PSModule/GitHub#638 keeps the full README, including use cases, platform notes, and the complete authentication guide including Azure Key Vault, and adds a documentation pointer.

Follow-up: apply the definition to the remaining standardization PRs, and sync Template-PSModule's README.

Round 2 additions

Following review of all 55 rollout PRs, the standard now also:

Renames the README showcase heading from Capabilities to Usage. Examples is still allowed; Capabilities is now disallowed and checked in README validation.
States that each repository stands on its own feet. It carries its own governance files and does not rely on the org .github fallback. The README must not include a ## Contributing section; the repository ships a self-contained CONTRIBUTING.md instead.
Requires agent onboarding files: AGENTS.md, CLAUDE.md with @AGENTS.md, and .github/copilot-instructions.md, all pointing to PSModule/docs and MSXOrg/docs.
Adds a placeholder guard so a module exporting any real command is not treated as a placeholder.
Tightens the PowerShell version policy to modern-only: minimum 7.6, track current and LTS, and drop 5.1 accommodation in PowerShell/index.md.
Adds Modules/Module-Types.md and extends Naming.md with REST-method to verb mapping, ConvertTo and ConvertFrom plus Format, Import, and Export, Hashtable as the data-module reference, and Context for user and module settings.

Follow-ups were filed as separate issues for framework 5.1 compatibility rules versus modern-only, Distributor rollout of the new mandatory files, and data-module naming conformance for Toml and Hashtable.

Round 3

Resolve the scope conflict

Repository-Defaults.md previously had a scope contradiction: the Scope section excluded documentation repositories such as PSModule/docs, while the Agent onboarding files and Required common files sections required every repository to carry agent onboarding files and to stand on its own.

The scope now states that two baseline expectations apply to every PSModule repository regardless of type:

agent onboarding files
repository self-sufficiency

The concrete file set and layout on the rest of the page remain module-specific.

Adopt the standard here

PSModule/docs previously carried none of the required agent onboarding files. This PR adds them so the repository that defines the standard also follows it:

AGENTS.md: cross-tool entry point pointing to psmodule.io and the MSX documentation
CLAUDE.md: @AGENTS.md import
.github/copilot-instructions.md: points to AGENTS.md

Copilot review addressed

examples/ is no longer described as a published surface in the README validation note, aligning with the rule that relocation is valid only to a published home.
The data round-trip sentence in Naming.md and Module-Types.md was completed.

Follow-up out of scope

An organization-wide rollout of the agent onboarding files is still needed. An audit of the org showed:

0/58 module repositories carry AGENTS.md
0/58 module repositories carry CLAUDE.md
0/4 docs repositories carry AGENTS.md
0/4 docs repositories carry CLAUDE.md
1 repository carries .github/copilot-instructions.md

That rollout should go through Distributor's mandatory file sets as this standard describes.

Trimming a module README must not delete unique information. Adds a content-preservation rule (keep/trim/relocate, never drop), makes the capabilities showcase mandatory for implemented modules, carves out an upstream attribution and licensing exception, fixes the copy/paste-hostile Get-Help example, and extends README validation.

github-actions · 2026-07-09T04:18:47Z

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
HTML	Pass ✅
JAVASCRIPT_ES	Pass ✅
JAVASCRIPT_PRETTIER	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter

The README publishes as the module landing page; a bare top-level docs/ is not published by the docs build. Correct the relocation guidance to only published homes (README, group overview pages under src/functions/public, comment-based help) and state that a longer README is acceptable rather than deleting narrative content to shorten it.

…7.6+ - Rename README showcase heading Capabilities -> Usage (Examples allowed); disallow Capabilities and add to README validation. - Each repo stands on its own: carries own governance files, no reliance on org .github fallback; README has no Contributing section (repo ships self-contained CONTRIBUTING.md). - Add agent onboarding files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) to required files + Distributor mandatory sets, pointing to PSModule/docs and MSXOrg/docs. - Placeholder guard: a module exporting any real command is not a placeholder. - Modern PowerShell only: minimum 7.6, track current + LTS; drop 5.1 accommodation. - New Module-Types.md (integration/API + data modules) + Naming.md rules (REST->verb, ConvertTo/From + Format/Import/Export); Hashtable is the data-module reference; Context for user + module settings.

Clarify Repository-Defaults scope so agent onboarding files and repository self-sufficiency apply to every PSModule repository, while the module file set and layout stay type-specific. This removes the contradiction with the 'every repository' / 'stand on its own' requirements that had excluded PSModule/docs. Dogfood the standard: add AGENTS.md, CLAUDE.md (@AGENTS.md import), and .github/copilot-instructions.md to PSModule/docs, which previously carried none of the required agent onboarding files.

Copilot

Pull request overview

Updates the PSModule PowerShell module standards to better preserve README content during standardization, formalize module archetype guidance (integration/API vs data), and establish consistent repository/agent onboarding defaults across repos.

Changes:

Adds a new “Module types” standards page and links it into the PowerShell Modules nav/index.
Expands repository defaults to require repo-local governance files plus agent onboarding entrypoints (AGENTS.md / CLAUDE.md / copilot-instructions).
Refines README and naming guidance (Usage showcase requirement, content preservation rules, REST→verb mapping, data-module verb vocabulary) and tightens the PowerShell support policy to modern-only (min 7.6).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/zensical.toml	Adds “Module types” to the docs navigation.
src/docs/PowerShell/Standard/Naming.md	Adds verb conventions for data modules and integration/API modules.
src/docs/PowerShell/Modules/Repository-Defaults.md	Updates README standardization rules + adds agent onboarding and repo self-sufficiency requirements.
src/docs/PowerShell/Modules/Module-Types.md	New page defining integration/API vs data module conventions and cross-links.
src/docs/PowerShell/Modules/index.md	Links to the new Module-Types page from the Modules landing page.
src/docs/PowerShell/index.md	Updates the supported PowerShell version policy (modern-only, min 7.6).
CLAUDE.md	Adds Claude entrypoint importing AGENTS.md.
AGENTS.md	Adds agent onboarding instructions for this docs repository.
.github/copilot-instructions.md	Adds Copilot instructions pointing to AGENTS.md.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ound-trip grammar - Repository-Defaults README validation no longer calls examples/ a published surface; it now aligns with the 'relocate only to a published home' rule (group overview page or comment-based help) and states repository-only locations such as examples/ must still be linked from the README. - Naming.md and Module-Types.md: complete the 'so data round-trips' clause -> 'so data can round-trip between the format and the object model'.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

…n Naming.md Replace the ambiguous ellipsis in 'Remove-…Entry' with the explicit '<Noun>' placeholder so it matches the verb vocabulary in Module-Types.md and is copy/paste-safe.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

…> template placeholder The README template uses 'Get-Help -Name <Command> -Examples' and the guidance tells authors to replace <Command>, but the validation Select-String only matched '-Name ''CommandName''' and <CommandName>, so a README shipping <Command> unchanged would pass. Add <Command> to the pattern list.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

…-modules sentence Removed the commas after GitHub and after Domeneshop; the service-client list is part of the subject, not a parenthetical, so 'GitHub and the service-client modules such as ... are integration modules' now reads correctly.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

…ble rows 'Read from a file or store into objects' read ambiguously (store-into adjacency). Reworded to 'Read objects from a file or store' to parallel the Export- row 'Write objects to a file or store'.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

…Select-String patterns in README check

Marius Storhaug (MariusStorhaug) · 2026-07-18T11:29:04Z

Split per-topic PRs created from this branch to reduce moving parts:\n\n- #65 README standard + rollout evidence\n- #66 Module archetypes guidance + docs nav wiring\n- #67 Repository onboarding defaults + self-sufficiency baseline\n\nIf this split looks right, we can close #61 after the split PRs are reviewed.

… detailed descriptions for each step

Establishes repository self-sufficiency standards and agent onboarding requirements by isolating agent framework setup and documentation conventions from the broader PR #61. ## Changes - Add [AGENTS.md](AGENTS.md) defining the agent framework directive and ecosystem installation/working guidelines - Add [CLAUDE.md](CLAUDE.md) importing AGENTS.md for Claude Code integration - Add [.github/copilot-instructions.md](.github/copilot-instructions.md) pointing to AGENTS.md for GitHub Copilot - Update [src/docs/Modules/Repository-Defaults.md](src/docs/Modules/Repository-Defaults.md) with self-sufficiency requirements and agent onboarding file standards - Clean up [.github/linters/.markdown-lint.yml](.github/linters/.markdown-lint.yml) formatting and add MD025 rule exception - Temporarily disable update-index actions (Update-ActionList, Update-FunctionAppList) in [.github/actions/update-index/src/main.ps1](.github/actions/update-index/src/main.ps1) - Remove [assets/javascripts/abbreviation-preview.js](src/docs/assets/javascripts/abbreviation-preview.js) ## Technical Details Splits agent-related conventions and repository self-sufficiency policy from PR #61 to enable focused review of onboarding standards. The AGENTS.md file serves as the single source of truth for agent framework setup and working patterns, while CLAUDE.md and .github/copilot-instructions.md delegate to it for consistent integration across IDE surfaces. - Relates to: #61

Module archetype guidance now documents Integration and Data modules with flexible transport and Context patterns. The guidance clarifies design choices for exposing or hiding transport abstractions, Context functions for targeting environments, and the ConvertFrom/ConvertTo data flow directions. ## New: Module archetype guidance PSModule modules fall into two standardized archetypes. The new Module-Types.md page documents: - **Integration (API) modules**: Wrap external services via REST or GraphQL. Commands map to resources and intents, not HTTP methods. Transport abstractions (REST/GraphQL functions) may be private, public, or combined with public Context depending on audience needs. - **Data modules**: Convert between data format representations and PowerShell objects. Conversion always flows through PSCustomObject as the neutral pivot, with ConvertFrom and ConvertTo functions moving bidirectionally. ## Changed: Transport abstraction is flexible, not prescriptive Transport, REST methods, and GraphQL functions do not have to be private. Modules now document three strategies: - **Private transport** (common): Keep REST/GraphQL helpers private. Public functions accept resolved inputs and typed objects. Follows Dependency Inversion at the network boundary. - **Public transport**: Expose REST or GraphQL functions for power users or module composition. - **Public Context**: Expose Context functions so users can configure and target specific contexts and environments directly. Module authors choose the strategy that best serves their audience. ## Changed: Context modules must expose functions and object types The Context module provides on-disk storage for user data and secrets organized by context and environment. Modules must expose functions and object types so users can programmatically target specific contexts and environments. Users need to select which environment or context their functions operate against. ## Improved: ConvertFrom/ConvertTo data flow clarity The verb vocabulary table now explicitly shows data flow directions: - **ConvertFrom-<Format>**: Format-specific input → PSCustomObject - **ConvertTo-<Format>**: PSCustomObject → Format-specific output ## Technical Details - Added `src/docs/Modules/Module-Types.md` with Integration and Data archetype guidance. - Updated `src/docs/Modules/index.md` with module section links. - Added cross-link from Repository-Defaults.md to module types. - Updated site navigation in `src/zensical.toml`. - Split from PR #61 to isolate module archetype guidance from README policy and onboarding defaults.

This PR extracts the README-focused part of #61 into its own reviewable scope. ## Included - README content-preservation and published-landing-page defaults in Repository-Defaults.md - README placeholder validation guard updates ## Why PR #61 combined multiple topics. This split isolates README policy so review can focus on one concern. ## Traceability - Split from: #61

Marius Storhaug (MariusStorhaug) added the enhancement label Jul 9, 2026

This was referenced Jul 9, 2026

📖 [Docs]: README pages now use the standard module landing-page format PSModule/NerdFonts#85

Open

📖 [Docs]: README pages now use the standard module landing-page format PSModule/GitHub#638

Open

Marius Storhaug (MariusStorhaug) added 2 commits July 9, 2026 06:51

Marius Storhaug (MariusStorhaug) changed the title ~~Preserve unique content in the README default~~ Standardize module README + repository, agent, and module-type defaults Jul 11, 2026

Marius Storhaug (MariusStorhaug) requested a review from Copilot July 12, 2026 00:21

Copilot started reviewing on behalf of Marius Storhaug (MariusStorhaug) July 12, 2026 00:21 View session