diff --git a/docs/src/content/docs/code-reference/architecture.mdx b/docs/src/content/docs/code-reference/architecture.mdx index 91e6d01a49..2580a0bde9 100644 --- a/docs/src/content/docs/code-reference/architecture.mdx +++ b/docs/src/content/docs/code-reference/architecture.mdx @@ -135,21 +135,31 @@ The **Win11 Creator** is a specialized subsystem within Winutil that creates cus ### Win11 Creator Components **Core Functions** (`functions/private/`): -- `Invoke-WinUtilISO.ps1`: Main orchestrator containing all Win11 Creator functions +- `Invoke-WinUtilISO.ps1`: Main orchestrator containing ISO workflow and helper functions - `Invoke-WinUtilISOBrowse`: ISO file selection dialog - `Invoke-WinUtilISOMountAndVerify`: Validates and mounts ISO, verifies it is an official Windows 11 ISO - `Invoke-WinUtilISOModify`: Launches modification in background runspace - - `Invoke-WinUtilISOExport`: Handles ISO and USB export + - `Invoke-WinUtilISOExport`: Builds bootable ISO via `oscdimg.exe` - `Invoke-WinUtilISOCheckExistingWork`: Recovers incomplete work sessions - `Invoke-WinUtilISOCleanAndReset`: Cleans up temp directories and resets UI - -- `Invoke-WinUtilISOScript.ps1`: Applies modifications to mounted install.wim - - Removes provisioned AppX packages (40+ bloatware apps) - - Injects drivers (optional) from the current system - - Removes OneDrive setup files - - Applies offline registry tweaks (hardware bypass, privacy, telemetry, OOBE) - - Deletes telemetry scheduled task definitions - - Pre-stages setup scripts from autounattend.xml + - `Write-WinUtilISOLog`: Posts log messages to UI status box and session log + - `Set-WinUtilISOStep`: Controls wizard navigation state + - `Get-WinUtilEditionIdFromName`: Maps edition display names to setup edition IDs + - `Invoke-WinUtilRobocopy`: Copies files with exit code verification + - `Find-WinUtilOscdimg` / `Get-WinUtilOscdimgPath`: Locates or installs `oscdimg.exe` + +- `Invoke-WinUtilISOUSB.ps1`: USB drive detection and formatting + - `Invoke-WinUtilISORefreshUSBDrives`: Enumerates USB drives + - `Get-WinUtilFreeDriveLetter`: Finds available drive letters + - `Invoke-WinUtilISOWriteUSB`: Formats USB drive as GPT/FAT32, splits WIM if needed, and copies files + +- `Invoke-WinUtilISOScript.ps1`: Prepares setup media and customizations + - Stages AppX removal (19 bloatware packages) into `autounattend.xml` for first logon + - Applies 50+ registry tweaks and scheduled-task cleanups via first-logon setup script + - Triggers OneDrive uninstall during first logon + - Stages setup script fallbacks to `sources\$OEM$\$$\Setup\Scripts\` + - Pins selected edition in `autounattend.xml` and writes `sources\ei.cfg` + - Injects eligible current system drivers into WIM images if enabled (WIM mount is only used for driver servicing) ### Win11 Creator Data Flow @@ -169,18 +179,17 @@ User optionally enables the Driver Injection checkbox ↓ Invoke-WinUtilISOModify (runs in background runspace) ├─ Create work directory: ~WinUtil_Win11ISO_[timestamp] - ├─ Copy ISO contents to disk (~5-6 GB) - ├─ Mount install.wim at selected edition/index + ├─ Copy ISO contents to disk via robocopy (~5-6 GB) ├─ Invoke-WinUtilISOScript: - │ ├─ Remove 40+ bloat AppX packages - │ ├─ Export and inject drivers (if enabled) - │ ├─ Remove OneDrive setup - │ ├─ Load offline registry hives - │ ├─ Apply 50+ registry tweaks (hardware bypass, privacy, telemetry, OOBE, etc.) - │ ├─ Delete telemetry scheduled task files - │ ├─ Pre-stage setup scripts from autounattend.xml to C:\Windows\Setup\Scripts\ - │ └─ Unload registry hives - ├─ Dismount and save the modified install.wim (~10+ minutes, slowest step) + │ ├─ Generate autounattend.xml with post-install script (19 AppX removals, 50+ tweaks, OneDrive uninstall) + │ ├─ Pin selected edition index in autounattend.xml (/IMAGE/INDEX) + │ ├─ Stage setup script fallbacks to sources\$OEM$\$$\Setup\Scripts\ + │ ├─ Write sources\ei.cfg and remove stale sources\PID.txt + │ └─ If driver injection enabled: + │ ├─ Export current system drivers via DISM + │ ├─ Exclude stale duplicate packages + │ ├─ Inject storage drivers into boot.wim index 2 and eligible drivers into install.wim + │ └─ Validate WIM metadata before and after injection ├─ Dismount source ISO └─ Report completion, enable export options ↓ @@ -191,12 +200,14 @@ Invoke-WinUtilISOExport (user chooses output) │ └─ Option 2: Write to USB ├─ Format USB as GPT - ├─ Create 512 MB EFI partition - ├─ Copy modified ISO contents + ├─ Create single FAT32 partition (capped at 32 GB) + ├─ Split install.wim into .swm files if > 3.8 GB + ├─ Copy files via robocopy └─ Output: Bootable USB (minimum 8 GB) ↓ Invoke-WinUtilISOCleanAndReset (optional) - └─ Delete temp working directory (~10-15 GB) + ├─ Dismount any open WIM mounts with discard + ├─ Delete temp working directory (~10-15 GB) └─ Reset UI to initial state ``` @@ -208,20 +219,29 @@ Invoke-WinUtilISOCleanAndReset (optional) - Checks image metadata for "Windows 11" string - Rejects custom, modified, or non-Windows 11 ISOs +**WIM Metadata Validation**: +- `Assert-WinUtilISOWimMetadata` validates critical fields (`Languages`, `Installation`, `Edition`, `ProductSuite`, `ProductType`) before and after driver injection +- Rejects damaged or incomplete WIM metadata before export + +**Edition Pinning & Setup Fallback**: +- Writes `sources\ei.cfg` and removes `sources\PID.txt` so setup does not use mismatched OEM product keys +- Pins the selected edition index in `autounattend.xml` (`/IMAGE/INDEX`) +- Stages fallback setup scripts under `sources\$OEM$\$$\Setup\Scripts\` with `UseConfigurationSet` enabled + **Work Session Recovery**: - Auto-detects incomplete work from previous sessions - Allows resuming the export step without re-running selection and modification - Prevents redundant modifications **Modification Safety**: -- All registry changes are documented in a script (reversible) +- Registry changes run during first logon via `WinUtil-PostInstall.ps1` - Original ISO never modified; only working copy -- Logged to `WinUtil_Win11ISO.log` for debugging -- DISM handles image dismount with automatic cleanup on error +- Logged to the WinUtil session log and the live UI status panel +- DISM handles image dismount with automatic cleanup and discard on error ### Win11 Creator Registry Tweaks -The `Invoke-WinUtilISOScript` function applies **50+ offline registry tweaks**: +The `Invoke-WinUtilISOScript` function applies **50+ registry tweaks** during setup and first logon: **Hardware Bypass**: - TPM 2.0 check bypass diff --git a/docs/src/content/docs/guides/win11creator.mdx b/docs/src/content/docs/guides/win11creator.mdx index 55ddc7103d..b1a41f0332 100644 --- a/docs/src/content/docs/guides/win11creator.mdx +++ b/docs/src/content/docs/guides/win11creator.mdx @@ -45,8 +45,8 @@ Once the ISO is verified, WinUtil moves to this step and shows the mounted drive Then click **Run Windows ISO Modification and Creator** to start the customization process. WinUtil will: **App & Component Removal:** -- **Remove 40+ bloat apps** — Clipchamp, Teams, Copilot, Dev Home, new Outlook, Bing apps, Solitaire, and more -- **Delete OneDrive setup** from the image +- **Remove 19 bloat apps** — Clipchamp, Teams, Dev Home, new Outlook, Bing apps, Solitaire, and more +- **Uninstall OneDrive** during first logon **System Customization:** - **Bypass hardware checks** — removes TPM, Secure Boot, CPU, RAM, and storage requirement enforcement so the ISO installs on unsupported hardware @@ -95,7 +95,7 @@ Once the modification is complete, choose how to save your image: 1. Click **Write Directly to a USB Drive**. 2. Select your USB drive from the dropdown (click **Refresh** if it doesn't appear). 3. Click **Erase & Write to USB** and confirm the warning — **all data on the drive will be permanently erased**. -4. WinUtil formats the drive as GPT with a 512 MB EFI partition and copies the modified Windows files. +4. WinUtil formats the drive as GPT with a single FAT32 partition (capped at 32 GB, splitting `install.wim` into `.swm` files if larger than 3.8 GB) and copies the modified Windows files. :::danger Double-check you have selected the correct drive before confirming. This operation cannot be undone.