Rewrite classic page transformation guidance around PnP PowerShell

[TaoziZ03]

Summary

• Rewrite the classic page transformation hub as a beginner-first, five-step workflow.
• Make PnP PowerShell the primary execution path from Microsoft 365 Assessment output.
• Add a dedicated transformed-page validation task.
• Move .NET, mappings, cross-site behavior, configuration, and videos under Reference while preserving their existing URLs.
• Route executable transformation guidance through one canonical PowerShell article instead of duplicating commands in Assessment pages.

Why

Stage 1 added the Classic Page Assessment and its handoff to page transformation. This draft starts Stage 2 by turning that handoff into a safe execution path.

The 423-page documentation dogfood demonstrated that MappingPercentage=100 doesn't guarantee successful or complete output: one selected page failed during mapping, and one zero-part page produced a blank target. The Stage 2 flow therefore treats readiness as a planning signal and makes representative-wave validation mandatory.

Current draft

Beginner workflow

The transformation hub now guides readers through:

1. Select candidates from completed Assessment coverage.
2. Resolve blockers and choose an in-place or cross-site target.
3. Prepare a tenant-owned PnP PowerShell application.
4. Transform a representative wave.
5. Validate every page before expanding the wave.

The same ordered workflow is stored in a reusable include.

PnP PowerShell primary path

The rewritten PowerShell task:

• Builds non-writing representative groups from classicpages.csv and classicpagewebparts.csv using page type, layout, and ordered Web Part signatures.
• Uses companion scripts to transform all selected representatives and to refuse expansion until the representative manifest and validated results match.
• Requires PowerShell 7.4.0 or later and a current PnP PowerShell release.
• Explains the mandatory tenant-owned application and client ID.
• Uses delegated SharePoint AllSites.Manage for pages that inherit library permissions.
• Reserves AllSites.FullControl for preserving item-level unique permissions.
• Resolves the exact approved file and converts by list item ID.
• Creates a draft target with -DontPublish.
• Preserves the source and omits -Overwrite, -TakeSourcePageName, and home-page replacement.
• Enables file logging and stops the wave on failures or content mismatches.

Validation

The new validation article covers:

• Source retention and target existence.
• Transformation logs and skipped mappings.
• Content, Web Parts, layout, links, images, metadata, permissions, and publication state.
• Blank and partial targets.
• Per-page wave records, approval ownership, and expansion gates.

Scope

This PR covers classic page transformation only.

It doesn't cover Lists, broad Extensibility, InfoPath, AddInsACS, Alerts, Groupify, end-to-end site modernization, or Scanner archival. Scanner archival remains Stage 3.

Existing advanced-reference files and public URLs remain unchanged.

Grounding and validation

• Rebased on merged PR Add Classic Page Assessment and transformation handoff guidance #10961 and the latest upstream main.
• Checked against current ConvertTo-PnPPage, Connect-PnPOnline, Get-PnPFile, Get-PnPProperty, and app-registration documentation/help.
• Checked against the current PnP PowerShell cmdlet implementation and PnP Framework behavior.
• PowerShell examples parse successfully.
• All documented PnP parameters exist in the tested PnP PowerShell module.
• Changed local links and includes resolve.
• Safety pressure-testing identified and corrected exact-file, permission-inheritance, publication-state, and runtime prerequisites.
• The companion script Pester suite passes 7/7 tests; the embedded Learn copies match the reviewed script files by SHA-256.

Companion script PR

The full script source is embedded in a dedicated Learn article in this PR. The reusable script files are also under review in:

pnp/modernization#676

Remaining before ready for maintainer review

• Validate and update advanced security, approach, configuration, .NET, mapping, and video references.
• Complete publishing-page, custom-layout, and cross-site validation.
• Run current-head OpenPublishing and documentation-agent review.

This PR is intentionally a draft for author review while those slices continue.

[learn-build-service-prod]

Learn Build status updates of commit 1c78a0b:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/transform/modernize-userinterface-site-pages-validation.md	💡Suggestion	View	Details
docs/toc.yml	✅Succeeded	View
docs/transform/assess-sharepoint-modernization.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-report.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-requirements.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-run.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages.md	✅Succeeded	View
docs/transform/assessment-tool-publishing-coverage.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages-powershell.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages.md	✅Succeeded	View
includes/snippets/modernization/classic-page-transformation-workflow.md	✅Succeeded	View

docs/transform/modernize-userinterface-site-pages-validation.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit a6d51c5:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/transform/modernize-userinterface-site-pages-validation.md	💡Suggestion	View	Details
docs/toc.yml	✅Succeeded	View
docs/transform/assess-sharepoint-modernization.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-report.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-requirements.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-run.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages.md	✅Succeeded	View
docs/transform/assessment-tool-publishing-coverage.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages-powershell.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages.md	✅Succeeded	View
includes/snippets/modernization/classic-page-transformation-workflow.md	✅Succeeded	View

docs/transform/modernize-userinterface-site-pages-validation.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

Learn Build status updates of commit 05a7745:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/transform/modernize-userinterface-site-pages-validation.md	💡Suggestion	View	Details
docs/toc.yml	✅Succeeded	View
docs/transform/assess-sharepoint-modernization.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-report.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-requirements.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-run.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages.md	✅Succeeded	View
docs/transform/assessment-tool-publishing-coverage.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages-powershell.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages.md	✅Succeeded	View
includes/snippets/modernization/classic-page-transformation-workflow.md	✅Succeeded	View

docs/transform/modernize-userinterface-site-pages-validation.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit ccb85b1:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/transform/modernize-userinterface-site-pages-validation.md	💡Suggestion	View	Details
docs/toc.yml	✅Succeeded	View
docs/transform/assess-sharepoint-modernization.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-report.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-requirements.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-run.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages.md	✅Succeeded	View
docs/transform/assessment-tool-publishing-coverage.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages-powershell.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages.md	✅Succeeded	View
includes/snippets/modernization/classic-page-transformation-workflow.md	✅Succeeded	View

docs/transform/modernize-userinterface-site-pages-validation.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit b2f20b3:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/transform/modernize-userinterface-site-pages-validation.md	💡Suggestion	View	Details
docs/transform/modernize-userinterface-site-pages-wave-scripts.md	💡Suggestion	View	Details
docs/toc.yml	✅Succeeded	View
docs/transform/assess-sharepoint-modernization.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-report.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-requirements.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-run.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages.md	✅Succeeded	View
docs/transform/assessment-tool-publishing-coverage.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages-powershell.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages.md	✅Succeeded	View
includes/scripts/page-transformation/Convert-RepresentativePages.ps1	✅Succeeded	View
includes/scripts/page-transformation/Convert-SelectedPages.ps1	✅Succeeded	View
includes/scripts/page-transformation/PageTransformation.Common.ps1	✅Succeeded	View
includes/snippets/modernization/classic-page-transformation-workflow.md	✅Succeeded	View

docs/transform/modernize-userinterface-site-pages-validation.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

docs/transform/modernize-userinterface-site-pages-wave-scripts.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 111b7c9:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/transform/modernize-userinterface-site-pages-validation.md	💡Suggestion	View	Details
docs/transform/modernize-userinterface-site-pages-wave-scripts.md	💡Suggestion	View	Details
docs/toc.yml	✅Succeeded	View
docs/transform/assess-sharepoint-modernization.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-report.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-requirements.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages-run.md	✅Succeeded	View
docs/transform/assessment-tool-classic-pages.md	✅Succeeded	View
docs/transform/assessment-tool-publishing-coverage.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages-powershell.md	✅Succeeded	View
docs/transform/modernize-userinterface-site-pages.md	✅Succeeded	View
includes/scripts/page-transformation/Convert-RepresentativePages.ps1	✅Succeeded	View
includes/scripts/page-transformation/Convert-SelectedPages.ps1	✅Succeeded	View
includes/scripts/page-transformation/PageTransformation.Common.ps1	✅Succeeded	View
includes/snippets/modernization/classic-page-transformation-workflow.md	✅Succeeded	View

docs/transform/modernize-userinterface-site-pages-validation.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

docs/transform/modernize-userinterface-site-pages-wave-scripts.md

• Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.