Preserve unique content in the README default

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.

Author: MariusStorhaug

src/docs/PowerShell/Modules/Repository-Defaults.md

@@ -171,6 +171,8 @@ Dependabot PRs still go through normal review. Automated dependency updates are
 
 A module README is a start page, not the command reference or full manual. It brings a reader in, answers the first questions, and sends them to the right documentation surface.
 
+Making the README shorter must not delete unique information. The README is often the only place that carries certain content: prerequisites, platform and dependency notes, authentication and setup guidance, operational behavior such as caching, state, or update and versioning semantics, and upstream attribution. None of that is generated from comment-based help, so trimming the README must preserve it — keep it on the landing page when it belongs there, or relocate it to `docs/`, `examples/`, or comment-based help. Only remove content that is genuinely duplicated by generated command documentation.
+
 The README answers these questions, in this order:
 
 | Question | Module README responsibility |
@@ -224,15 +226,25 @@ Use PowerShell help and command discovery for module details:
 
 ```powershell
 Get-Command -Module <ModuleName>
-Get-Help -Name 'CommandName' -Examples
+Get-Help -Name <Command> -Examples
 ```
 ````
 
-README pages should include a short capabilities or usage showcase before the documentation link when the module has working capabilities. Keep that section focused on discovery and marketing: show representative outcomes, not every command, parameter, or edge case.
+In the documentation examples, replace `<Command>` with a real command exported by the module, for example `Get-Help -Name Get-GitHubRepository -Examples`, so the snippet runs as written. Do not ship placeholder tokens such as `'CommandName'` or `<CommandName>` as if they were runnable commands.
+
+Implemented modules must include the capabilities or usage showcase before the documentation link. Keep it focused on discovery: show one to three representative outcomes, not every command, parameter, or edge case. A landing page with only an installation snippet and a documentation link is not enough for a module that has working commands.
+
+Keep, trim, or relocate content — do not delete it:
+
+- **Keep on the landing page:** the overview, prerequisites and requirements (PowerShell version, supported platforms, module or native dependencies), installation, the capabilities showcase, and the short operational notes a reader needs before first use.
+- **Trim:** exhaustive command inventories, parameter tables, and repetitive examples that differ only by a parameter. These come from comment-based help — point to `Get-Help` and the documentation site instead of restating them.
+- **Relocate, never drop:** long-form guides and unique conceptual content that is too detailed for a landing page, such as authentication and setup walkthroughs, deep operational detail, and end-to-end scenarios. Move them to `docs/` or `examples/`, or into comment-based help, and link to them. If there is no other home for the content yet, keep a condensed version in the README rather than deleting it.
+
+Retain upstream attribution and licensing context. Credit, acknowledgements, donation notes, and third-party license notices for wrapped or bundled work must stay in the README, or move to a clearly linked place. The rule below about community and policy sections does not apply to attribution the project is expected to carry.
 
 README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long reference sections when those details are already produced from comment-based help.
 
-Do not add a community-file or policy link section by default. Readers can find standard repository files such as `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md` through GitHub conventions and the repository file tree. Link them only when the module has an unusual rule the user must know before using it.
+Do not add a community-file or policy link section by default. Readers can find standard repository files such as `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md` through GitHub conventions and the repository file tree. Link them only when the module has an unusual rule the user must know before using it, or when it carries required upstream attribution.
 
 ## Placeholder and in-progress repositories
 
@@ -267,12 +279,15 @@ Before opening a README-only PR, check that the README follows the default and d
 ```powershell
 Select-String -Path README.md -SimpleMatch -Pattern 'Greet-Entity', 'PSModuleTemplate', 'YourModuleName'
 Select-String -Path README.md -SimpleMatch -Pattern '{{ NAME }}', '{{ DESCRIPTION }}'
+Select-String -Path README.md -SimpleMatch -Pattern "-Name 'CommandName'", '<CommandName>'
 Select-String -Path README.md -Pattern '^## Commands$'
 git diff --check -- README.md
 ```
 
 `Template-PSModule` is the exception: it intentionally keeps `{{ NAME }}` and `{{ DESCRIPTION }}` tokens because those are template inputs.
 
+For an implemented module, also confirm the README keeps a capabilities or usage showcase and that any unique content removed from the previous version — prerequisites, setup or authentication guidance, operational notes, or upstream attribution — was relocated to `docs/`, `examples/`, or comment-based help rather than deleted.
+
 ## Documentation ownership
 
 Command details belong in comment-based help and generated documentation. The README can showcase capability, then points to those sources for reference detail.