PlatyPS 2e: document the docs/ schema conversion for consumers #154

Part of #120 (Phase 2 — PlatyPS migration, #105).

Re-scoped 2026-08-24. The original scope — a one-shot conversion of this
repository's committed docs/ markdown to the 1.x schema — is a no-op. There is
nothing here to convert:

$ git ls-files docs
docs/migration-v0.8-to-v1.0.md

Command markdown is generated into docs/ at build time and has never been
committed. The only tracked file under docs/ is the migration guide, which is
hand-written prose and is not PlatyPS output.

The second half of the original scope survives intact and is now the whole issue:
consumers do commit docs/ trees, they face a real conversion, and nothing else
on the route tells them how to do it. That guidance was already listed here as a
deliverable rather than an afterthought.

Scope

Write the consumer-facing guidance for converting a committed docs/ tree from the
0.14.x schema to the 1.x schema, as an entry in docs/migration-v0.8-to-v1.0.md.

The one-shot itself is short:

$markdownFile = Measure-PlatyPSMarkdown -Path .\docs\en-US\*.md
$markdownFile | Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path { $_.FilePath } |
    Export-MarkdownCommandHelp -OutputFolder .\docs\en-US -Force

The guidance is the part that needs work: what breaks, what to inspect, and what a
consumer should do if they hit it.

Watch for

• Content loss is the real hazard. Hand-written examples and notes are the parts
  most likely to be dropped in conversion. The guidance must tell consumers to review
  the diff for content, not just schema churn.
• Verify the one-shot before publishing it. Because this repository commits no
  command markdown, the snippet above cannot be exercised against docs/ here. Run it
  against generated output, or against a scratch copy of a real consumer's docs/
  tree, before shipping it as advice. Untested migration snippets are worse than none.
• This is the home for the "Consumer guidance for the docs/ schema conversion" item
  in [Tracking] PowerShellBuild v1.0.0 roadmap #120's Not yet specified section.

Done when

docs/migration-v0.8-to-v1.0.md documents the conversion for consumers, and the
one-shot in it has actually been run against a real 0.14.x docs/ tree rather than
transcribed from the PlatyPS documentation.