Layout rules omit that domain grouping changes a command's canonical help URL

[MariusStorhaug]

Summary

The module layout rules tell authors to group functions by domain and to place a <Group>.md overview beside them. They never mention the consequence that grouping has on published documentation URLs: a command's generated page moves under its group, so its canonical address changes and every .LINK in the module must change with it.

There is currently no mention of .LINK, canonical function URLs, or the PublicHelpLink contract anywhere in this repository.

How this was hit

Regrouping PSModule/Yaml into domain folders (PSModule/Yaml#50, delivered in PSModule/Yaml#53) followed the layout rules exactly. The first CI run failed anyway:

[-] Should put the canonical documentation link first for Conversion/ConvertFrom-Yaml (ID: PublicHelpLink)
    Expected: 'https://psmodule.io/Yaml/Functions/Conversion/ConvertFrom-Yaml/'

Document-PSModule relocates each generated command page to mirror the source layout, so Functions/ConvertFrom-Yaml/ became Functions/Conversion/ConvertFrom-Yaml/, and Test-PSModule's PublicHelpLink test enforces the new form. Ninety-eight .LINK values needed updating — seven public commands plus ninety-one private helpers pointing at the public command they serve.

The framework caught it, so nothing shipped wrong. But it cost a full CI round trip on a change that had otherwise followed the standard to the letter, and it is entirely predictable from the docs' own mechanism. Anyone regrouping an existing module hits it identically, and the larger the module the more helper links there are to miss.

Why the current text does not prevent it

"Group by domain" and "group documentation pages with source" both describe the source tree. Nothing connects that to the published site, so there is no reason for a reader to expect a URL change — the link update looks like an unrelated concern until CI says otherwise.

Proposed change

Add one layout rule stating the canonical .LINK form, and a short paragraph noting that regrouping an existing module changes those URLs and that the link update belongs in the same change.

Acceptance criteria

• The layout rules state the canonical published URL form for a grouped public command.
• The rule notes that private helpers link the public command they serve.
• PublicHelpLink is named, so a failing check is traceable back to the standard.
• Authors regrouping an existing module are told the link update is part of that work, not follow-up.

Out of scope

• Changing the URL scheme, the Document-PSModule relocation behaviour, or the PublicHelpLink test itself.