Rewrite classic page transformation guidance around PnP PowerShell

docs/toc.yml

@@ -1858,6 +1858,38 @@
       items:
       - name: Transform with PnP PowerShell
         href: transform/modernize-userinterface-site-pages-powershell.md
+      - name: Validate transformed pages
+        href: transform/modernize-userinterface-site-pages-validation.md
+      - name: Reference
+        items:
+        - name: Page wave script reference
+          href: transform/modernize-userinterface-site-pages-wave-scripts.md
+        - name: In-place versus cross-site transformation
+          href: transform/modernize-userinterface-site-pages-approach.md
+        - name: Security requirements
+          href: transform/modernize-userinterface-site-pages-security.md
+        - name: Configuration options
+          href: transform/modernize-userinterface-site-pages-configuration.md
+        - name: Classic Web Part mappings
+          href: transform/modernize-userinterface-site-pages-webparts.md
+        - name: Page transformation model
+          href: transform/modernize-userinterface-site-pages-model.md
+        - name: Publishing page transformation model
+          href: transform/modernize-userinterface-site-pages-model-publishing.md
+        - name: Functions and selectors
+          href: transform/modernize-userinterface-site-pages-api.md
+        - name: User mapping
+          href: transform/modernize-userinterface-site-pages-usermapping.md
+        - name: URL mapping
+          href: transform/modernize-userinterface-site-pages-urlmapping.md
+        - name: Term mapping
+          href: transform/modernize-userinterface-site-pages-termmapping.md
+        - name: Layout transformation
+          href: transform/modernize-userinterface-site-pages-layout.md
+        - name: .NET integration
+          href: transform/modernize-userinterface-site-pages-dotnet.md
+        - name: Videos
+          href: transform/modernize-userinterface-site-pages-videos.md
   - name: Modernizing your classic SharePoint sites
     items:
     - name: Overview
@@ -1875,37 +1907,8 @@
           href: transform/modernize-userinterface-lists-and-libraries-rollout.md
         - name: Opting out from modern
           href: transform/modernize-userinterface-lists-and-libraries-optout.md
-      - name: Transform classic pages to modern pages
-        href: transform/modernize-userinterface-site-pages.md
-        items:
-        - name: Page transformation via PowerShell
-          href: transform/modernize-userinterface-site-pages-powershell.md
-        - name: Page transformation via .Net
-          href: transform/modernize-userinterface-site-pages-dotnet.md
-        - name: Page transformation videos
-          href: transform/modernize-userinterface-site-pages-videos.md
-        - name: Page transformation configuration options
-          href: transform/modernize-userinterface-site-pages-configuration.md
-        - name: Classic web part to modern mapping
-          href: transform/modernize-userinterface-site-pages-webparts.md
-        - name: In-place versus cross-site page transformation
-          href: transform/modernize-userinterface-site-pages-approach.md
-        - name: Page transformation security
-          href: transform/modernize-userinterface-site-pages-security.md
-        - name: Page transformation model
-          href: transform/modernize-userinterface-site-pages-model.md
-        - name: Publishing Page transformation model
-          href: transform/modernize-userinterface-site-pages-model-publishing.md
-        - name: Page transformation Functions and Selectors
-          href: transform/modernize-userinterface-site-pages-api.md
-        - name: User mapping
-          href: transform/modernize-userinterface-site-pages-usermapping.md
-        - name: URL mapping
-          href: transform/modernize-userinterface-site-pages-urlmapping.md
-        - name: Term mapping
-          href: transform/modernize-userinterface-site-pages-termmapping.md
-        - name: Page layout mapping
-          href: transform/modernize-userinterface-site-pages-layout.md
+      - name: Assess and transform classic pages
+        href: transform/assess-sharepoint-modernization.md
     - name: SharePoint Modernization scanner
       items:
       - name: Overview

docs/transform/assess-sharepoint-modernization.md

@@ -36,6 +36,7 @@ Mapping readiness is an input to planning, not a guarantee that the transformed
 1. [Interpret and prioritize the page results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ## Reference
 

docs/transform/assessment-tool-classic-pages-report.md

@@ -1,7 +1,7 @@
 ---
 title: Interpret the classic pages assessment report
 description: Use page, web part, usage, and rollup results from the Microsoft 365 Assessment tool to plan SharePoint page modernization.
-ms.date: 07/27/2026
+ms.date: 07/29/2026
 ms.localizationpriority: high
 ms.service: sharepoint
 ---
@@ -52,6 +52,9 @@ Audit usage is a planning signal, not a raw web analytics counter. Always check
 | `skipped` | Audit collection wasn't run for the site, such as in an unsupported cloud. |
 | `error` | An unexpected post-scan exception occurred. Review `SkipReason` and the assessment log. |
 
+> [!IMPORTANT]
+> Sovereign-cloud assessments don't provide page Audit usage. Don't interpret missing or skipped usage rows as zero activity. Prioritize with `ModifiedAt`, known page importance, and business-owner input.
+
 When a site's audit query succeeded, the absence of a page row means that no matching events were returned for that page in the requested window. Treat an absent row as zero activity only after confirming successful coverage for the site.
 
 If `SkipReason` starts with `QueryTimeout`, Microsoft Purview didn't complete the query during Assessment's 90-minute wait. When no audit chunk succeeds, the row has `QueryStatus=failed`; treat its zero counts as failed coverage, not as evidence of no activity. This is different from `NoPermission`, which indicates a missing Audit permission.
@@ -81,7 +84,29 @@ Use `classicpagewebparts.csv` for the per-page decision:
 
 Use `classicwebpartunique.csv` to identify web part types that affect many pages. `InMappingFile` is weaker than `IsMappable`: it only means that the type has an entry in the mapping file.
 
-The current Assessment implementation deliberately treats the community mappings for `ScriptEditorWebPart` and `SimpleFormWebPart` as unavailable. It also doesn't support the legacy Scanner's on-disk mapping-file override.
+The current Assessment implementation deliberately treats the community mappings for `ScriptEditorWebPart` and `SimpleFormWebPart` as unavailable. It also doesn't support an on-disk mapping-file override.
+
+This Assessment result means that the default readiness model doesn't approve those Web Parts. PnP transformation can optionally route Script Editor and Simple Form content to the open-source Community Script Editor after that solution is installed and `-UseCommunityScriptEditor` is selected.
+
+> [!CAUTION]
+> A script editor can execute custom code in the page. Treat this as an advanced remediation decision with security review and a separately validated page. The Assessment-driven batch scripts don't enable Community Script Editor.
+
+See [Classic Web Part mappings](modernize-userinterface-site-pages-webparts.md#enabling-the-use-of-the-community-script-editor-web-part-to-be-used-during-transformation).
+
+### Decide the next action
+
+Evaluate the table from top to bottom and use the first matching row. Mapping-based decisions apply only after coverage and page-type routing are complete.
+
+| Assessment result | Decision | Next action |
+| --- | --- | --- |
+| Site collection or web didn't finish | Coverage blocked | Resolve the scan failure before interpreting page counts or readiness. |
+| Page type is Blog, ASPX, or Delve Blog | Mapping score isn't actionable | Follow the [page-type support guidance](assessment-tool-classic-pages.md#page-type-support) instead of using the readiness percentage. |
+| Page type is Publishing | Advanced backlog | Review the layout and missing portal-level inputs before defining a separate target and procedure. |
+| Wiki or Web Part page is a home page | Separate approval required | Keep it out of the first wave and define URL, navigation, and rollback behavior before transformation. |
+| Wiki or Web Part page has `WebPartCount=0` and `MappingPercentage=0` with an enrichment error | Page scan failed | Review the log and rerun Assessment before selecting the page. |
+| Wiki or Web Part page has `WebPartCount=0` and `MappingPercentage=100` | Manual review required | Open the source page and confirm whether Assessment missed visible content. Don't place it in an automated wave. |
+| Wiki or Web Part page has `WebPartCount>0`, `MappingPercentage=100`, and no unmapped Web Parts | Representative-pilot candidate | Group it by layout and ordered Web Part signature, transform a draft, and validate the result. |
+| Wiki or Web Part page has `MappingPercentage<100` or one or more `UnmappedWebParts` | Remediation required | Replace the blocking Web Parts or define and separately validate a custom mapping before transformation. |
 
 ## Use rollups
 
@@ -90,15 +115,15 @@ Use `classicwebsummaries.csv` and `classicsitesummaries.csv` to identify:
 - Webs and site collections with the most classic pages.
 - Pages with fully mappable or unmapped web parts.
 - Average mapping percentage across pages that contain web parts.
-- Default home pages that can be replaced as an early modernization wave.
+- Home pages that require a separate approved backlog for URL, navigation, and rollback planning.
 
 Rollups are useful for sequencing, but return to the page and web part CSV files before making a remediation decision.
 
 ## Review publishing portals
 
 `classicpublishingsitesummaries.csv` provides a site-collection-level publishing summary. Detailed legacy web-level publishing configuration isn't included.
 
-See [Understand publishing portal coverage](assessment-tool-publishing-coverage.md) before replacing an established Publishing Scanner workflow.
+See [Understand publishing portal coverage](assessment-tool-publishing-coverage.md) before planning publishing page transformation.
 
 ## Move from assessment to transformation
 
@@ -123,64 +148,17 @@ Turn the report into a transformation backlog:
 
 The Assessment app is read-only. Use a separate PnP PowerShell connection with permission to create or update pages in the source or target web.
 
-### Transform one selected Wiki or Web Part page
-
-This example selects one assessed page and transforms it in place. Filter on the exact `PageUrl` that you approved for the migration wave.
-
-```powershell
-$row = Import-Csv .\classicpages.csv |
-  Where-Object PageUrl -eq '/sites/source/SitePages/ApprovedPage.aspx' |
-  Select-Object -First 1
-
-if ($row.PageType -notin @('WikiPage', 'WebPartPage')) {
-  throw "This example only handles WikiPage and WebPartPage rows."
-}
-
-$sourceWebUrl = if ($row.WebUrl -eq '/') {
-  $row.SiteUrl
-}
-else {
-  "$($row.SiteUrl.TrimEnd('/'))$($row.WebUrl)"
-}
-
-$source = Connect-PnPOnline `
-  -Url $sourceWebUrl `
-  -Interactive `
-  -ClientId <application-id> `
-  -ReturnConnection
-
-$libraryPath = $row.ListUrl.TrimEnd('/')
-if (-not $row.PageUrl.StartsWith("$libraryPath/", [StringComparison]::OrdinalIgnoreCase)) {
-  throw "PageUrl isn't under ListUrl."
-}
-
-$pageRelativeToLibrary = $row.PageUrl.Substring($libraryPath.Length).TrimStart('/')
-$pageName = [IO.Path]::GetFileName($pageRelativeToLibrary)
-$folder = [IO.Path]::GetDirectoryName($pageRelativeToLibrary) -replace '\\', '/'
-$libraryName = [Uri]::UnescapeDataString([IO.Path]::GetFileName($libraryPath))
-
-$parameters = @{
-  Identity = $pageName
-  Connection = $source
-}
-
-if ($libraryName -ne 'SitePages') {
-  $parameters.Library = $libraryName
-}
-if (-not [string]::IsNullOrWhiteSpace($folder)) {
-  $parameters.Folder = $folder
-}
-
-ConvertTo-PnPPage @parameters
-```
+### Continue with the transformation task
+
+Use the field mapping to approve the exact Assessment row and record the expected content. Then follow [Transform selected classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md) for the current application, permission, source-identity, draft-output, logging, and validation safeguards.
 
 Route other page types deliberately:
 
 - `PublishingPage`: use `-PublishingPage`, a target web, and the [publishing page-layout model](modernize-userinterface-site-pages-model-publishing.md).
 - `BlogPage`: use `-BlogPage`, `PageName` as the blog-title identity, and a target web. Blog rows don't receive the detailed mapping-readiness enrichment described for Wiki, Web Part, and Publishing pages.
 - `ASPXPage` and `DelveBlogPage`: exclude them from this automated transformation queue; the page assessment doesn't provide an equivalent readiness path for them.
 
-Start with [Transform classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md). Use the [page transformation model](modernize-userinterface-site-pages-model.md) for custom Web Part mappings and the [publishing model](modernize-userinterface-site-pages-model-publishing.md) for publishing page layouts.
+Start with [Transform selected classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md), and then [validate each transformed page](modernize-userinterface-site-pages-validation.md). Use the [page transformation model](modernize-userinterface-site-pages-model.md) for custom Web Part mappings and the [publishing model](modernize-userinterface-site-pages-model-publishing.md) for publishing page layouts.
 
 ## Power BI and CSV
 

docs/transform/assessment-tool-classic-pages-requirements.md

@@ -1,7 +1,7 @@
 ---
 title: Requirements for the classic pages assessment
 description: Configure authentication, permissions, audit access, and a supported environment for the Microsoft 365 Assessment tool classic pages component.
-ms.date: 07/27/2026
+ms.date: 07/29/2026
 ms.localizationpriority: high
 ms.service: sharepoint
 ---
@@ -26,7 +26,37 @@ The tool supports the following authentication modes:
 
 Application authentication is recommended for a full-tenant assessment. A delegated assessment can access only the sites that the signed-in account can access.
 
-For general application-registration steps, see [Configure authentication](https://pnp.github.io/pnpassessment/using-the-assessment-tool/setupauth.html).
+Use a dedicated Microsoft Entra application and grant only the permission type required by the selected authentication mode. The permission tables on this page are authoritative for the Classic Pages component in Assessment 1.16.0.
+
+### Create a delegated application
+
+1. In the Microsoft Entra admin center, open **App registrations**, and select **New registration**.
+1. Enter a name. Under **Supported account types**, select **Single tenant only - \<your tenant\>**, and register the application.
+1. Under **API permissions**, select **Add a permission** > **Microsoft Graph** > **Delegated permissions**, select `Sites.Read.All` and `User.Read`, and select **Add permissions**.
+1. Select **Add a permission** > **SharePoint** > **Delegated permissions**, select `AllSites.Read`, and select **Add permissions**.
+1. If the assessment will collect Audit usage, add the Microsoft Graph delegated permission `AuditLogsQuery-SharePoint.Read.All`.
+1. Select **Grant admin consent for \<tenant\>**, and select **Yes**.
+1. Copy the **Application (client) ID** for `--applicationid`.
+
+For Interactive authentication, under **Authentication**, select **Add a platform** > **Mobile and desktop applications**, add the custom redirect URI `http://localhost`, and select **Configure**.
+
+For Device authentication, a redirect URI isn't required. Under **Authentication** > **Advanced settings**, set **Allow public client flows** to **Yes**, and select **Save**.
+
+An application used for both Interactive and Device authentication requires both settings.
+
+### Register an application-authentication application
+
+1. Create a single-tenant app registration. A redirect URI isn't required for application authentication.
+1. Under **API permissions**, remove the default delegated Microsoft Graph `User.Read` permission.
+1. Select **Add a permission** > **Microsoft Graph** > **Application permissions**, select `Sites.Read.All`, and select **Add permissions**.
+1. Select **Add a permission** > **SharePoint** > **Application permissions**, select `Sites.Read.All`, and select **Add permissions**.
+1. If the assessment will collect Audit usage, add the Microsoft Graph application permission `AuditLogsQuery-SharePoint.Read.All`.
+1. Under **Certificates & secrets** > **Certificates**, select **Upload certificate**, choose the public certificate, and select **Add**.
+1. Select **Grant admin consent for \<tenant\>**, and select **Yes**.
+1. Copy the **Application (client) ID** for `--applicationid`.
+1. Install or securely provide the matching private-key certificate to the account that runs the assessment.
+
+For additional certificate-generation options, see [Configure authentication](https://pnp.github.io/pnpassessment/using-the-assessment-tool/setupauth.html). Don't copy broader permissions from a generic sample; use the Classic Pages permission tables on this page.
 
 ### Application certificate
 
@@ -53,6 +83,8 @@ The page inventory reads web part configuration through the SharePoint `LimitedW
 
 Grant admin consent for the configured permissions before starting the assessment.
 
+These permissions are read-only. They don't allow PnP PowerShell to create or update modern pages. Use a separate transformation application and the [PnP PowerShell transformation permission guidance](modernize-userinterface-site-pages-powershell.md#permissions).
+
 ## Audit usage permission
 
 Unless you specify `--skipusageinformation`, the assessment queries Microsoft Graph for `ClassicPageViewed`, `ClassicPageCreated`, and `ClassicPageEdited` audit events.
@@ -101,6 +133,7 @@ Assessment output can contain tenant and site URLs, application identifiers, use
 1. [Interpret and prioritize the classic page results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ## Reference
 

docs/transform/assessment-tool-classic-pages-run.md

@@ -1,7 +1,7 @@
 ---
 title: Run a classic pages assessment
 description: Start, scope, monitor, and report a Microsoft 365 Assessment tool classic pages assessment.
-ms.date: 07/27/2026
+ms.date: 07/29/2026
 ms.localizationpriority: high
 ms.service: sharepoint
 ---
@@ -69,6 +69,9 @@ The sites file contains one absolute site-collection URL per line. Don't combine
 | `--homepageonly` | Filters the page inventory to the home page of each web. It doesn't filter site-scoped Audit results. |
 | `--threads <number>` | Changes parallelism. Start with 4 to 8 threads when throttling is a concern. |
 
+> [!IMPORTANT]
+> Microsoft Graph Audit Query isn't available to this assessment in sovereign-cloud environments, including GCC High, DoD, and Microsoft 365 operated by 21Vianet. Use `--skipusageinformation`; prioritize pages with `ModifiedAt`, page importance, and business-owner input instead of Audit activity.
+
 For example, assess only home pages, export web part properties, and skip audit usage:
 
 ```powershell
@@ -139,6 +142,7 @@ Use `--delimiter Semicolon` when a semicolon-delimited export is required. Use `
 1. [Interpret and prioritize the classic page results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ## Reference