Backfill MS Learn doc fixes and add validation gate

[Jaylyn Barbee (Jaylyn-Barbee)]

What & why

The MS Learn docs at MicrosoftDocs/windows-dev-docs-pr are generated from this repo by scripts/port-mslearn-docs.ps1. Copilot left review suggestions on the v0.5.0 docs PR (windows-dev-docs-pr#7161). Because that output is regenerated every release, editing the docs PR directly would be overwritten — so these fixes are made at the source of truth here, plus a generator fix and a new validation gate so the same issues can't recur.

Source content fixes (reconciling Copilot suggestions)

• ui-automation.md: interactive-desktop blockquote → [!IMPORTANT] Learn alert
• electron/js-phi-silica.md + electron/phi-silica-addon.md: replaced marketing sample text ("powerful tool…") with neutral instructional text
• electron/js-winml.md: fixed the WinML sample link to the Microsoft-hosted microsoft/electron-on-windows-gallery

Front-matter descriptions

• Added compliant <!-- description: --> markers (115–145 chars, unquoted, distinct from the H1) to 18 mslearn docs that previously defaulted their description to the page title
• Shortened 2 pre-existing over-length descriptions (README, usage)
• Removed remaining "powerful" marketing wording

CI / generator fixes

• port-mslearn-docs.ps1: normalized the guides/index.md heading boundary so the extracted block no longer emits a stray carriage return
• port-mslearn-docs.ps1: runs the new validator at Step 0.5 (fail fast; the release Release_MSLearn stage enforces it for free)
• New scripts/validate-mslearn-docs.ps1: hard-fails on description rules + banned marketing words; warns (non-fatal) on blockquote-as-callout

Verification

• Regenerated locally; validator passes; diff of regenerated output vs PR #7161 (ignoring ms.date) shows only the 9 intended fixes, no regressions
• Targeted code-review pass; one flagged issue (misaligned warn line numbers) fixed

Follow-up

Regenerated docs are staged on the local winapp-cli/v0.5.0 branch to update PR #7161. Merge this once the next Copilot review on that branch is clean.

---

Update: left-nav TOC (toc.yml)

The winapp CLI node on MS Learn had no nested left-nav — pages were only reachable via Related topics — because the winapp-cli folder had no toc.yml and the parent hub/apps/toc.yml node pointed straight at index.md. port-mslearn-docs.ps1 now generates toc.yml (Step 7) from the ported output: overview, commands, debugging, UI Automation, and a Framework guides subtree with a nested Electron group. It warns if any ported page is missing from the tree.

Rollout (the child TOC alone isn't enough — the parent docs-repo TOC must branch into it): docs PR windows-dev-docs-pr#7187 adds the generated dev-tools/winapp-cli/toc.yml and points both parent hub/apps/toc.yml winapp CLI entries at it (also fixes the winappCLI → winapp CLI label). That PR is nav-only — no ms.date churn, tracks released v0.5.0.

Update: review feedback addressed

Addresses the Copilot and pr-review (Zach) comments on this PR:

• YAML quoting (Copilot validate:54) — detect leading block indicators (-/?) and start/end-only indicators, not just always-special chars.
• Shared helper (Zach M1) — extracted description/title/topic resolution + YAML quoting into scripts/mslearn-doc-lib.ps1, dot-sourced by both the generator and the validator (removes the duplicated "keep in sync" logic).
• Callout false positive (Copilot validate:143) — track whether the contiguous blockquote opened with an alert marker, so multi-paragraph [!NOTE] blocks no longer warn.
• Banned-word line numbers (Zach L2) — errors now report the offending line(s).
• Validator tests (Zach H1) — new scripts/tests/validate-mslearn-docs.Tests.ps1 (Pester 5, 23 tests) covering description bounds, banned words, YAML-unsafe values, callout behaviour, and 0/1 exit codes; wired into build-cli.ps1.
• WinML sample link (Copilot js-winml.md) — no longer promises a not-yet-existing gallery sample; points generically at the Electron on Windows gallery.
• Root README marketing word (Zach L1) — "Many powerful Windows APIs" → "Many Windows APIs".
• mslearn-doc-lib.ps1 staged into the release mslearn-source artifact.

[Copilot]

Pull request overview

Backfills MS Learn documentation fixes and adds source validation before documentation generation.

Changes:

• Adds validation for descriptions, marketing terms, and callout syntax.
• Updates descriptions and neutralizes promotional wording.
• Fixes guide generation formatting and a WinML sample link.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/validate-mslearn-docs.ps1	Adds MS Learn validation.
scripts/port-mslearn-docs.ps1	Runs validation and fixes heading spacing.
docs/usage.md	Shortens description.
docs/ui-automation.md	Uses Learn alert syntax.
docs/README.md	Revises description and wording.
docs/guides/tauri.md	Adds description.
docs/guides/shell-completion.md	Adds description.
docs/guides/rust.md	Adds description.
docs/guides/packaging-cli.md	Adds description.
docs/guides/flutter.md	Adds description.
docs/guides/electron/winml-addon.md	Adds description.
docs/guides/electron/setup.md	Adds description.
docs/guides/electron/phi-silica-addon.md	Adds description and neutral sample text.
docs/guides/electron/packaging.md	Adds description.
docs/guides/electron/js-winml.md	Adds description and fixes sample link.
docs/guides/electron/js-phi-silica.md	Adds description and neutral sample text.
docs/guides/electron/js-notification.md	Adds description.
docs/guides/electron/js-file-picker.md	Adds description.
docs/guides/electron/index.md	Adds description.
docs/guides/electron/cpp-notification-addon.md	Adds description.
docs/guides/dotnet.md	Adds description.
docs/guides/cpp.md	Adds description.
docs/debugging.md	Adds description.

---

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

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

[github-actions]

Build Metrics Report

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	36.63 MB	36.63 MB	✅ 0.0 KB (0.00%)
CLI (x64)	36.82 MB	36.82 MB	✅ 0.0 KB (0.00%)
MSIX (ARM64)	15.26 MB	15.26 MB	📈 +0.1 KB (+0.00%)
MSIX (x64)	16.20 MB	16.20 MB	📈 +0.1 KB (+0.00%)
NPM Package	31.83 MB	31.83 MB	📈 +0.2 KB (+0.00%)
NuGet Package	31.86 MB	31.86 MB	📉 -0.1 KB (-0.00%)

Test Results

✅ 3719 passed, 4 skipped out of 3723 tests in 652.2s (+36.5s vs. baseline)

Test Coverage

✅ 94.5% line coverage, 88.6% branch coverage · ✅ no change vs. baseline

CLI Startup Time

50ms median (x64, winapp --version) · ✅ no change vs. baseline

---

Updated 2026-07-27 14:40:03 UTC · commit d2afdd3 · workflow run

[Zach Teutsch (zateutsch)]

🤖 AI-generated review (winappcli pr-review skill) — verify before acting.

PR Review — jay/0.5-docs-backfill vs origin/main (2 commits, 24 files, +206/-8)

Summary: Critical: 0 · High: 1 · Medium: 1 · Low: 2

Clean, low-risk docs + tooling PR. The highest-risk concern (a self-inconsistent gate or skipped porting) was disproven at runtime. Nothing blocks merge.

Coverage

Dimension	Result
security	✓ clean
correctness	✓ clean
cli-ux	⚠ 1 finding (1 dropped after runtime refutation)
alternative-solution	⚠ 1 finding
necessity-simplicity	n/a (no new user-facing surface)
test-coverage	⚠ 1 finding
docs-and-samples	⚠ 1 finding
packaging	✓ clean
multi-model	✓ reviewed independently by GPT (gpt-5.6-sol)
regression	✓ port flow runs end-to-end (exit 0, 22 md files)
validation	✓ validator + port run at runtime; critical exit-propagation hypothesis refuted

Findings

ID	Location	Domain	Finding
H1	scripts/validate-mslearn-docs.ps1:49-163	test-coverage	New release-gating validator has no tests
M1	scripts/validate-mslearn-docs.ps1:47-122	alternative-solution	Duplicates Get-FrontMatter logic in port-mslearn-docs.ps1
L1	README.md:71	docs-and-samples	Root README still says "Many powerful Windows APIs"
L2	scripts/validate-mslearn-docs.ps1:127-129	cli-ux	Banned-word errors omit line numbers

---

H1 — scripts/validate-mslearn-docs.ps1:49-163 · high · test-coverage

The validator now hard-gates the release porting job but has no Pester tests pinning its rules or exit codes. It works today (ran it: 21 docs, 24 warnings, 0 errors, exit 0; invalid input → exit 1), but a regex regression could silently break releases with no safety net. Multi-model note: GPT pass rated test coverage clean at critical/high severity — severity disputed.
Recommendation: Add a Pester suite with fixture docs covering description bounds, banned words, YAML-special chars, non-fatal callout warnings, and 0/1 exit codes.

M1 — scripts/validate-mslearn-docs.ps1:47-122 · medium · alternative-solution

Description resolution + $YamlSpecialPattern quoting logic is a second copy of Get-FrontMatter (~L277-302 in port-mslearn-docs.ps1); the file header itself says "keep in sync." Two copies will drift.
Recommendation: Extract shared MS Learn metadata constants/helpers into a dot-sourced .ps1 both scripts import.

L1 — README.md:71 · low · docs-and-samples

This PR removed "Many powerful Windows APIs" → "Many Windows APIs" in docs/README.md but left the identical phrase in the root README.md. Root README isn't mslearn-opted so the new gate won't catch it, but it's inconsistent with the PR's marketing-word cleanup.
Recommendation: Reword the root README line to match.

L2 — scripts/validate-mslearn-docs.ps1:127-129 · low · cli-ux

Banned-word errors report file + word but not line number, slowing CI fixes.
Recommendation: Report matching line number(s), like the callout check already does.

---

Dropped after validation

cli-ux flagged the "Fix the reported issues before porting" message as unreachable (theory: the validator's exit 0 kills the parent host). Refuted at runtime: a child .ps1 calling exit 0 via & only sets $LASTEXITCODE; the parent continues. Independently reproduced by the GPT multi-model pass, and port-mslearn-docs.ps1 ran fully to exit 0 producing 22 md files. Porting is not skipped; the message is reachable.

Coverage notes

• security: No unsafe process launch, no ReDoS in validator regexes, release.yml staging adds no 1ES injection vector, changed URL (github.com/microsoft/electron-on-windows-gallery) returns HTTP 200.
• correctness: Validator logic (opt-in window, description resolution, code-fence line preservation, callout off-by-one, exit codes) sound; ran validator + port end-to-end, both exit 0.
• packaging: Both scripts stage into the same mslearn-source/scripts dir so $PSScriptRoot resolves the validator; port passes staged mslearn-source/docs as -DocsRoot; no version.json/csproj/npm impact.
• docs-and-samples: All 21 mslearn docs satisfy the new gate (115-145 chars, no YAML-special, no banned words, distinct from title).

[Zach Teutsch (zateutsch)]

Some minor polish comments for your judgement, approving and you can address what you think is necessary.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

scripts/port-mslearn-docs.ps1:84

• This pre-generation check never validates pages synthesized later by the port script. In particular, guides/index.md is generated with a hard-coded 114-character description at line 480, below this PR's 115-character minimum, so the validator passes while the emitted Learn page still violates the rule. Validate the generated output (including synthesized pages), or apply a shared metadata-validation helper when generating this page, and add a regression test for its front matter.

& pwsh -NoProfile -File $validator -DocsRoot $DocsRoot