chore: import upstream snapshot with attribution

doc/devdocs/tools/bug-report-tool.md

@@ -0,0 +1,119 @@
+# Bug Report Tool
+
+The Bug Report Tool is a utility that collects logs and system information to help diagnose issues with PowerToys. It creates a comprehensive report that can be shared with developers to help troubleshoot problems.
+
+## Location and Access
+
+- Source code: `/tools/BugReportTool/`
+- Users can trigger the tool via:
+  - Right-click on PowerToys tray icon → Report Bug
+  - Left-click on tray icon → Open Settings → Bug Report Tool
+
+## What It Does
+
+The Bug Report Tool creates a zip file on the desktop named "PowerToys_Report_[date]_[time].zip" containing logs and system information. It:
+
+1. Copies logs from PowerToys application directories
+2. Collects system information relevant to PowerToys functionality
+3. Redacts sensitive information
+4. Packages everything into a single zip file for easy sharing
+
+## Information Collected
+
+### Logs
+- Copies logs from:
+  - `%LOCALAPPDATA%\Microsoft\PowerToys\Logs` - Regular logs
+  - `%USERPROFILE%\AppData\LocalLow\Microsoft\PowerToys` - Low-privilege logs
+
+### System Information
+- Windows version and build information
+- Language and locale settings
+- Monitor information (crucial for FancyZones and multi-monitor scenarios)
+- .NET installation details
+- PowerToys registry entries
+- Group Policy Object (GPO) settings
+- Application compatibility mode settings
+- Event Viewer logs related to PowerToys executables
+- PowerToys installer logs
+- Windows 11 context menu package information
+
+### PowerToys Configuration
+- Settings files
+- Module configurations
+- Installation details
+- File structure and integrity (with hashes)
+
+## Key Files in the Report
+
+* `compatibility-tab-info.txt` - Information about [compatibility settings](https://support.microsoft.com/windows/make-older-apps-or-programs-compatible-with-windows-783d6dd7-b439-bdb0-0490-54eea0f45938) set for certain PowerToys executables both in the user and system scope.
+* `context-menu-packages.txt` - Information about the packages that are registered for the new Windows 11 context menu.
+* `dotnet-installation-info.txt` - Information about the installed .NET versions.
+* `EventViewer-*.xml` - These files contain event logs from the Windows Event Viewer for the executable specified in the file name.
+* `EventViewer-Microsoft-Windows-AppXDeploymentServer/Operational.xml` - Contains event logs from the AppXDeployment-Server which are useful for diagnosing MSIX installation issues.
+* `gpo-configuration-info.txt` - Information about the configured [GPO](doc/devdocs/processes/gpo.md).
+* `installationFolderStructure.txt` - Information about the folder structure of the installation. All lines with files have the following structure: `FileName Version MD5Hash`.
+* `last_version_run.json` - Information about the last version of PowerToys that was run.
+* `log_settings.json` - Information about the log level settings.
+* `monitor-report-info.txt` - Information about the monitors connected to the system. This file is created by the [monitor info report tool](/doc/devdocs/tools/monitor-info-report.md).
+* `oobe_settings.json` - Information about the OOBE settings.
+* `registry-report-info.txt` - Information about the registry keys that are used by PowerToys.
+* `settings_placement.json` - Information about the placement of the settings window.
+* `settings-telemetry.json` - Information about the last time telemetry data was sent.
+* `UpdateState.json` - Information about the last update check and the current status of the update download.
+* `windows-settings.txt` - Information about the Windows language settings.
+* `windows-version.txt` - Information about the Windows version.
+
+## Privacy Considerations
+
+The tool redacts certain types of private information:
+- Mouse Without Borders security keys
+- FancyZones app zone history
+- User-specific paths
+- Machine names
+
+## Implementation Details
+
+The tool is implemented as a C# console application that:
+1. Creates a temporary directory
+2. Copies logs and configuration files to this directory
+3. Runs commands to collect system information
+4. Redacts sensitive information
+5. Compresses everything into a zip file
+6. Cleans up the temporary directory
+
+### Core Components
+
+- `BugReportTool.exe` - Main executable
+- Helper classes for collecting specific types of information
+- Redaction logic to remove sensitive data
+
+## Extending the Bug Report Tool
+
+When adding new PowerToys features, the Bug Report Tool may need to be updated to collect relevant information. Areas to consider:
+
+1. New log locations to include
+2. Additional registry keys to examine
+3. New GPO values to report
+4. Process names to include in Event Viewer data collection
+5. New configuration files to include
+
+## Build Process
+
+The Bug Report Tool is built separately from the main PowerToys solution:
+
+1. Path from root: `tools\BugReportTool\BugReportTool.sln`
+2. Must be built before building the installer
+3. Built version is included in the PowerToys installer
+
+### Building from the Command Line
+
+```
+nuget restore .\tools\BugReportTool\BugReportTool.sln
+msbuild -p:Platform=x64 -p:Configuration=Release .\tools\BugReportTool\BugReportTool.sln
+```
+
+### Building from Visual Studio
+
+1. Open `tools\BugReportTool\BugReportTool.sln`
+2. Set the Solution Configuration to `Release`
+3. Build the solution

doc/devdocs/tools/build-tools.md

@@ -0,0 +1,27 @@
+# [Build tools](/tools/build/)
+
+These build tools help building PowerToys projects.
+
+## [build-essentials.ps1](/tools/build/build-essentials.ps1)
+
+A script that builds certain specified PowerToys projects. You can edit the `$ProjectsToBuild` variable to specify which projects to build.
+
+## [convert-resx-to-rc.ps1](/tools/build/convert-resx-to-rc.ps1)
+
+This script converts a .resx file to a .rc file, so it can be used in a C++ project. More information on localization can be found in the [localization guide](/doc/devdocs/localization.md).
+
+## [convert-stringtable-to-resx.ps1](/tools/build/convert-stringtable-to-resx.ps1)
+
+This script converts a stringtable to a .resx file, so it can be used in a C# project. More information about this script can be found in the [localization guide](/doc/devdocs/localization.md).
+
+## [move-and-rename-resx.ps1](/tools/build/move-and-rename-resx.ps1)
+
+This script is used by the pipeline to move the .resx files to the correct location, so that they can be localized into different languages.
+
+## [move-uwp-resw.ps1](/tools/build/move-uwp-resw.ps1)
+
+This script is used by the pipeline to move the .resw files to the correct location, so that they can be localized into different languages.
+
+## [versionSetting.ps1](/tools/build/versionSetting.ps1)
+
+Sets `version.props` file with the version number.

doc/devdocs/tools/debugging-tools.md

@@ -0,0 +1,111 @@
+# PowerToys Debugging Tools
+
+PowerToys includes several specialized tools to help with debugging and troubleshooting. These tools are designed to make it easier to diagnose issues with PowerToys features.
+
+## FancyZones Debugging Tools
+
+### FancyZones Hit Test Tool
+
+- Location: `/tools/FancyZonesHitTest/`
+- Purpose: Tests FancyZones layout selection logic
+- Functionality:
+  - Simulates mouse cursor positions
+  - Highlights which zone would be selected
+  - Helps debug zone detection issues
+
+### FancyZones Draw Layout Test
+
+- Location: `/tools/FancyZonesDrawLayoutTest/`
+- Purpose: Tests FancyZones layout drawing logic
+- Functionality:
+  - Visualizes how layouts are drawn
+  - Helps debug rendering issues
+  - Tests different monitor configurations
+
+### FancyZones Zonable Tester
+
+- Location: `/tools/FancyZonesZonableTester/`
+- Purpose: Tests if a window is "zonable" (can be moved to zones)
+- Functionality:
+  - Checks if windows match criteria for zone placement
+  - Helps debug why certain windows can't be zoned
+
+## Monitor Information Tools
+
+### Monitor Info Report
+
+- Location: `/tools/MonitorPickerTool/`
+- Purpose: Diagnostic tool for identifying WinAPI bugs related to physical monitor detection
+- Functionality:
+  - Lists all connected monitors
+  - Shows detailed monitor information
+  - Helps debug multi-monitor scenarios
+
+## Window Information Tools
+
+### Styles Report Tool
+
+- Location: `/tools/StylesReportTool/`
+- Purpose: Collect information about an open window
+- Functionality:
+  - Reports window styles
+  - Shows window class information
+  - Helps debug window-related issues in modules like FancyZones
+
+### Build Process
+
+The Styles Report Tool is built separately from the main PowerToys solution:
+
+```
+nuget restore .\tools\StylesReportTool\StylesReportTool.sln
+msbuild -p:Platform=x64 -p:Configuration=Release .\tools\StylesReportTool\StylesReportTool.sln
+```
+
+## Shell-Related Debugging Tools
+
+### PowerRenameContextMenu Test
+
+- Location: `/tools/PowerRenameContextMenuTest/`
+- Purpose: Tests PowerRename context menu integration
+- Functionality:
+  - Simulates right-click context menu
+  - Helps debug shell extension issues
+
+## Verification Tools
+
+### Verification Scripts
+
+- Location: `/tools/verification-scripts/`
+- Purpose: Scripts to verify PowerToys installation and functionality
+- Functionality:
+  - Verify binary integrity
+  - Check registry entries
+  - Test module loading
+
+## Other Debugging Tools
+
+### Clean Up Tool
+
+- Location: `/tools/CleanUp/`
+- Purpose: Clean up PowerToys installation artifacts
+- Functionality:
+  - Removes registry entries
+  - Deletes settings files
+  - Helps with clean reinstallation
+
+### Using Debugging Tools
+
+1. Most tools can be run directly from the command line
+2. Some tools require administrator privileges
+3. Tools are typically used during development or for advanced troubleshooting
+4. Bug Report Tool can collect and package the output from several of these tools
+
+## Adding New Debugging Tools
+
+When creating new debugging tools:
+
+1. Place the tool in the `/tools/` directory
+2. Follow existing naming conventions
+3. Document the tool in this file
+4. Include a README.md in the tool's directory
+5. Consider adding the tool's output to the Bug Report Tool if appropriate

doc/devdocs/tools/fuzzingtesting.md

@@ -0,0 +1,243 @@
+# Fuzzing Testing in PowerToys
+
+## Overview
+
+Fuzzing is an automated testing technique that helps identify vulnerabilities and bugs by feeding random, invalid, or unexpected data into the application. This is especially important for PowerToys modules that handle file input/output or user input, such as Hosts File Editor, Registry Preview, and others.
+
+PowerToys integrates Microsoft's OneFuzz service to systematically discover edge cases and unexpected behaviors that could lead to crashes or security vulnerabilities. Fuzzing testing is a requirement from the security team to ensure robust and secure modules.
+
+## Why Fuzzing Matters
+
+- **Security Enhancement**: Identifies potential security vulnerabilities before they reach production
+- **Stability Improvement**: Discovers edge cases that might cause crashes
+- **Automated Bug Discovery**: Finds bugs that traditional testing might miss
+- **Reduced Manual Testing**: Automates the process of testing with unusual inputs
+
+## Types of Fuzzing in PowerToys
+
+PowerToys supports two types of fuzzing depending on the module's implementation language:
+
+1. **.NET Fuzzing** - For C# modules (using [OneFuzz](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/fuzzing-dotnet-code))
+2. **C++ Fuzzing** - For native C++ modules using [libFuzzer](https://llvm.org/docs/LibFuzzer.html)
+
+## Setting Up .NET Fuzzing Tests
+
+### Step 1: Add a Fuzzing Test Project
+
+Create a new test project within your module folder. Ensure the project name follows the format `*.FuzzTests`.
+
+### Step 2: Configure the Project
+
+1. Set up a `.NET 10 (Windows)` project
+   - Note: OneFuzz's .NET fuzzing is runtime-agnostic (".NET Core targets are preferred") and keys off the build drop directory, so PowerToys fuzz projects target net10 like the rest of the repo. Older guidance pinned .NET 8; that is no longer required.
+
+2. Add the required files to your fuzzing test project:
+   - Create fuzzing test code
+   - Add `OneFuzzConfig.json` configuration file
+
+### Step 3: Configure OneFuzzConfig.json
+
+The `OneFuzzConfig.json` file provides critical information for deploying fuzzing jobs. For detailed guidance, see the [OneFuzzConfig V3 Documentation](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/onefuzzconfig/onefuzzconfigv3).
+
+```json
+{
+  "fuzzers": [
+    {
+      "name": "YourModuleFuzzer",
+      "fuzzerLibrary": "libfuzzer-dotnet",
+      "targetAssembly": "YourModule.FuzzTests.dll",
+      "targetClass": "YourModule.FuzzTests.FuzzTestClass",
+      "targetMethod": "FuzzTest",
+      "FuzzingTargetBinaries": [
+        "YourModule.FuzzTests.dll"
+      ]
+    }
+  ],
+  "adoTemplate": [
+    {
+      "AssignedTo": "leilzh@microsoft.com",
+      "jobNotificationEmail": "PowerToys@microsoft.com"
+    }
+  ],
+  "oneFuzzJobs": [
+    {
+      "projectName": "PowerToys",
+      "targetName": "YourModule",
+      "jobDependencies": {
+        "binaries": [
+          "PowerToys\\x64\\Debug\\tests\\YourModule.FuzzTests\\net10.0-windows10.0.26100.0\\**"
+        ]
+      }
+    }
+  ],
+  "configVersion": "3.0.0"
+}
+```
+
+Key fields to update:
+1. Update the `targetAssembly`, `targetClass`, `targetMethod`, and `FuzzingTargetBinaries` fields
+2. Set the `AssignedTo` and `jobNotificationEmail` to your Microsoft email
+3. Update the `projectName` and `targetName` fields
+4. Define job dependencies pointing to your compiled fuzzing tests
+
+### Step 4: Configure the OneFuzz Pipeline
+
+Modify the patterns in the job steps within [job-fuzz.yml](https://github.com/microsoft/PowerToys/blob/main/.pipelines/v2/templates/job-fuzz.yml) to match your fuzzing project name:
+
+```yaml
+- download: current
+  displayName: Download artifacts
+  artifact: $(ArtifactName)
+  patterns: |-
+    **/tests/*.FuzzTests/**
+```
+
+## Setting Up C++ Fuzzing Tests
+
+### Step 1: Create a New C++ Project
+
+- Use the **Empty Project** template
+- Name it `<ModuleName>.FuzzingTest`
+
+### Step 2: Update Build Configuration
+
+- In **Configuration Manager**, uncheck Build for both Release|ARM64, Debug|ARM64 and Debug|x64 configurations
+- ARM64 is not supported for fuzzing tests
+
+### Step 3: Enable ASan and libFuzzer in .vcxproj
+
+Edit the project file to enable fuzzing:
+
+```xml
+<PropertyGroup>
+  <EnableASAN>true</EnableASAN>
+  <EnableFuzzer>true</EnableFuzzer>
+</PropertyGroup>
+```
+
+### Step 4: Add Fuzzing Compiler Flags
+
+Add these to `AdditionalOptions` under the `Fuzzing` configuration:
+
+```xml
+/fsanitize=address
+/fsanitize-coverage=inline-8bit-counters
+/fsanitize-coverage=edge
+/fsanitize-coverage=trace-cmp
+/fsanitize-coverage=trace-div
+%(AdditionalOptions)
+```
+
+### Step 5: Link the Sanitizer Coverage Runtime
+
+In `Linker → Input → Additional Dependencies`, add:
+
+```text
+$(VCToolsInstallDir)lib\$(Platform)\libsancov.lib
+```
+
+### Step 6: Copy Required Runtime DLL
+
+Add a `PostBuildEvent` to copy the ASAN DLL:
+
+```xml
+<Command>
+  xcopy /y "$(VCToolsInstallDir)bin\Hostx64\x64\clang_rt.asan_dynamic-x86_64.dll" "$(OutDir)"
+</Command>
+```
+
+### Step 7: Add Preprocessor Definitions
+
+To avoid annotation issues, add these to the `Preprocessor Definitions`:
+
+```text
+_DISABLE_VECTOR_ANNOTATION;_DISABLE_STRING_ANNOTATION
+```
+
+### Step 8: Implement the Entry Point
+
+Every C++ fuzzing project must expose this function:
+
+```cpp
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
+{
+    std::string input(reinterpret_cast<const char*>(data), size);
+
+    try
+    {
+        // Call your module with the input here
+    }
+    catch (...) {}
+
+    return 0;
+}
+```
+
+## Running Fuzzing Tests
+
+### Running Locally (.NET)
+
+To run .NET fuzzing tests locally, follow the [Running a .NET Fuzz Target Locally](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/fuzzing-dotnet-code#extra-running-a-net-fuzz-target-locally) guide:
+
+```powershell
+# Instrument the assembly
+.\dotnet-fuzzing-windows\sharpfuzz\SharpFuzz.CommandLine.exe path\to\YourModule.FuzzTests.dll
+
+# Set environment variables
+$env:LIBFUZZER_DOTNET_TARGET_ASSEMBLY="path\to\YourModule.FuzzTests.dll"
+$env:LIBFUZZER_DOTNET_TARGET_CLASS="YourModule.FuzzTests.FuzzTestClass"
+$env:LIBFUZZER_DOTNET_TARGET_METHOD="FuzzTest"
+
+# Run the fuzzer
+.\dotnet-fuzzing-windows\libfuzzer-dotnet\libfuzzer-dotnet.exe --target_path=dotnet-fuzzing-windows\LibFuzzerDotnetLoader\LibFuzzerDotnetLoader.exe
+```
+
+### Running in the Cloud
+
+To submit a job to the OneFuzz cloud service, follow the [OneFuzz Cloud Testing Walkthrough](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/faq/notwindows/walkthrough):
+
+1. Run the pipeline:
+   - Navigate to the [fuzzing pipeline](https://microsoft.visualstudio.com/Dart/_build?definitionId=152899&view=runs)
+   - Click "Run pipeline"
+   - Choose your branch and start the run
+
+2. Alternative: Use [OIP (OneFuzz Ingestion Preparation) tool](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/oip/onefuzzingestionpreparationtool):
+   ```
+   oip submit --config .\OneFuzzConfig.json --drop-path <your_submission_directory> --platform windows --do-not-file-bugs --duration 1
+   ```
+   - Use `--do-not-file-bugs` to prevent automatic bug creation during initial testing
+   - `--duration` specifies the number of hours (default is 48 if not specified)
+
+3. OneFuzz will send you an email when the job has started with a link to view results
+
+## Reviewing Results
+
+1. You'll receive an email notification when your fuzzing job starts
+2. Click the link in the email to view the job status on the [OneFuzz Web UI](https://onefuzz-ui.microsoft.com/)
+3. The OneFuzz platform will show statistics like inputs processed, coverage, and any crashes found
+4. If the final status is "success," your fuzzing test is working correctly
+
+## Current Status
+
+PowerToys has implemented fuzzing for several modules:
+- Hosts File Editor
+- Registry Preview
+- Fancy Zones
+
+Modules that still need fuzzing implementation:
+- Environmental Variables
+- Keyboard Manager
+
+## Requesting Access to OneFuzz
+
+To log into the production instance of OneFuzz with the [CLI](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/downloading-cli), you must request access. Visit the [OneFuzz Access Request Page](https://myaccess.microsoft.com/@microsoft.onmicrosoft.com#/access-packages/6df691eb-e3d1-444b-b4b2-9e944dc794be).
+
+## Resources
+
+- [OneFuzz Documentation](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/fuzzing-dotnet-code)
+- [OneFuzzConfig V3 Documentation](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/onefuzzconfig/onefuzzconfigv3)
+- [OneFuzz Ingestion Preparation Tool](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/oip/onefuzzingestionpreparationtool)
+- [OneFuzz CLI Setup Guide](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/downloading-cli)
+- [OneFuzz Web UI](https://onefuzz-ui.microsoft.com/)
+- [libFuzzer Documentation](https://llvm.org/docs/LibFuzzer.html)
+- [OneFuzz Cloud Testing Walkthrough](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/faq/notwindows/walkthrough)

doc/devdocs/tools/installer-diagnostics.md

@@ -0,0 +1,93 @@
+# PowerToys Installer & Update Diagnostics
+
+A step-by-step guide for diagnosing installer and update issues reported by users.
+
+## Quick Reference: Key Files
+
+| File/Folder | Path | Contains |
+|---|---|---|
+| UpdateState.json | `%LOCALAPPDATA%\Microsoft\PowerToys\UpdateState.json` | Persisted update state machine |
+| Runner logs | `%LOCALAPPDATA%\Microsoft\PowerToys\RunnerLogs\runner-log_*.log` | Startup, update checks, cleanup |
+| Update logs | `%LOCALAPPDATA%\Microsoft\PowerToys\UpdateLogs\update-log_*.log` | PowerToys.Update.exe activity |
+| Updates folder | `%LOCALAPPDATA%\Microsoft\PowerToys\Updates\` | Downloaded installer files |
+
+> **Note:** These paths use `%LOCALAPPDATA%` (per-user AppData) regardless of whether PowerToys was installed per-user or per-machine. The data/settings location is always per-user.
+
+## Update State Values
+
+From `src/common/updating/updateState.h` (`UpdateState::State` enum):
+
+| Value | Name | Meaning |
+|---|---|---|
+| 0 | upToDate | No update needed |
+| 1 | errorDownloading | Download or install failed, will retry |
+| 2 | readyToDownload | New version found, not yet downloaded |
+| 3 | readyToInstall | Installer downloaded, waiting for user action |
+| 4 | networkError | GitHub API call failed |
+
+---
+
+## Symptom: Old update installers accumulating on disk
+
+### What to ask the user for
+
+1. Contents of `UpdateState.json`
+2. Runner logs (last few days from `RunnerLogs\`)
+3. Update logs (from `UpdateLogs\`, if they exist)
+4. List of files in `Updates\` folder (names + sizes)
+
+### Step 1: Check the running version
+
+In runner logs, look for the startup line:
+
+```
+[info] Scoobe: product_version=v0.XX.X last_version_run=v0.XX.X
+```
+
+- **If version < v0.73.0**: The pre-download cleanup (PR #27908) is missing. Each downloaded installer accumulates because cleanup only runs at startup when state is `upToDate`. Ask the user to manually upgrade to the latest version.
+- **If version >= v0.73.0**: The pre-download cleanup exists. Accumulation should not happen under normal conditions. Continue to Step 2.
+
+### Step 2: Check UpdateState.json
+
+```jsonc
+{"state": 3, "downloadedInstallerFilename": "powertoyssetup-0.98.1-x64.exe" /* additional fields may be present */}
+```
+
+- **state = 0 (upToDate)**: Cleanup should run at startup. If files are accumulating, check runner logs for "Failed to delete" warnings (Step 4).
+- **state = 3 (readyToInstall)**: An installer is downloaded but never installed. Cleanup at startup is skipped (by design, to preserve the pending installer). On v0.73+, cleanup can still occur when a future update check triggers a new download (pre-download cleanup path).
+- **state = 1 (errorDownloading)**: A previous download or install failed. Startup cleanup is skipped (state is not `upToDate`). On v0.73+, cleanup runs before the next installer download is attempted.
+- **state = 2 or 4**: Startup cleanup is skipped. On v0.73+, cleanup runs before the next installer download is attempted.
+
+### Step 3: Check if PowerToys.Update.exe has ever run
+
+- **UpdateLogs directory missing**: This suggests `PowerToys.Update.exe` may never have been launched, or it did not progress far enough to create logs. The user may never have triggered an install, or Stage 1 may have failed before Stage 2 could run.
+- **UpdateLogs exist but show only "logger is initialized"**: The exe launched but the command-line argument didn't match any action (possible argument parsing issue).
+- **UpdateLogs show install activity**: The update process ran. Check for success/failure.
+
+### Step 4: Check runner logs for cleanup evidence
+
+Search for these patterns:
+
+| Log pattern | Meaning |
+|---|---|
+| `Failed to delete installer file ... Access is denied` | File locked by AV, another process, or permissions issue |
+| `Failed to delete log file ...` | Same, for old log files |
+| `Discovered new version` | Periodic update check ran |
+| `New version is already downloaded` | State is `readyToInstall` and filename matches — no re-download, no cleanup |
+| No cleanup-related entries at all | Inconclusive by itself — `cleanup_updates()` is silent on success. Corroborate with the Updates folder contents (Step 5) and the running version (Step 1). |
+
+### Step 5: Check the Updates folder contents
+
+- **All different versions**: Cleanup likely did not run across multiple update cycles. Confirm with the running version (Step 1) and update state before concluding a state gate issue.
+- **Duplicate filenames**: Unusual — would suggest repeated download without cleanup.
+- **Single file matching `downloadedInstallerFilename`**: Normal for `readyToInstall` state.
+
+### Common root causes
+
+| Root cause | Evidence | Fix |
+|---|---|---|
+| Running pre-v0.73.0 binary | `product_version` < v0.73.0 in runner log | Manually upgrade to latest |
+| State stuck at `readyToInstall` (pre-v0.73) | `"state": 3` in UpdateState.json, no UpdateLogs | Manually upgrade to latest |
+| File lock preventing deletion | "Failed to delete ... Access is denied" in runner logs | Check AV software, reboot and retry |
+| Update installer never launched | No UpdateLogs directory | Check if update notifications are disabled by GPO or setting |
+| Install fails silently | UpdateLogs show init but no install activity | Check related issues: #46966, #46967, #46969 |

doc/devdocs/tools/monitor-info-report.md

@@ -0,0 +1,22 @@
+# [Monitor info report tool](/tools/MonitorReportTool)
+
+A small diagnostic tool which helps identifying WinAPI bugs related to the physical monitor detection. When launched, it creates a log file like this:
+
+```text
+GetSystemMetrics = 2
+GetMonitorInfo OK
+EnumDisplayDevices OK:
+        DeviceID = \\?\DISPLAY#VSCBD34#5&25664547&0&UID4355#{e6f07b5f-ee97-4a90-b076-33f57bf4eaa7}
+        DeviceKey = \Registry\Machine\System\CurrentControlSet\Control\Class\{4d36e96e-e325-11ce-bfc1-08002be10318}\0002
+        DeviceName = \\.\DISPLAY1\Monitor0
+        DeviceString = Generic PnP Monitor
+GetMonitorInfo OK
+EnumDisplayDevices OK:
+        DeviceID = \\?\DISPLAY#ENC2682#5&25664547&0&UID4357#{e6f07b5f-ee97-4a90-b076-33f57bf4eaa7}
+        DeviceKey = \Registry\Machine\System\CurrentControlSet\Control\Class\{4d36e96e-e325-11ce-bfc1-08002be10318}\0003
+        DeviceName = \\.\DISPLAY2\Monitor0
+        DeviceString = Generic PnP Monitor
+EnumDisplayMonitors OK
+```
+
+and also duplicates the info to `stdout`.

doc/devdocs/tools/readme.md

@@ -0,0 +1,16 @@
+# PowerToys tools
+
+Tools in PowerToys are standalone apps and scripts that run outside of the PowerToys runner. They help developers and users to debug and test PowerToys features.
+
+The source code of the tools can be found in the [tools folder](/tools). The compiled tools are saved under `{PowerToysInstallPath}\tools`.
+
+## Overview of the tools
+
+Following tools are currently available:
+
+* [BugReportTool](bug-report-tool.md) - A tool to collect logs and system information for bug reports.
+* [Build tools](build-tools.md) - A set of scripts that help building PowerToys.
+* [Monitor info report](monitor-info-report.md) - A small diagnostic tool which helps identifying WinAPI bugs related to the physical monitor detection.
+* [project template](/tools/project_template/README.md) - A Visual Studio project template for a new PowerToys project.
+* [StylesReportTool](styles-report-tool.md) - A tool to collect information about an open window.
+* [Verification scripts](verification-scripts.md) - A set of scripts that help verifying the PowerToys installation.

doc/devdocs/tools/styles-report-tool.md

@@ -0,0 +1,12 @@
+# [Styles Report Tool](/tools/StylesReportTool/)
+
+The Styles Report Tool is a tool to collect information about an open window. Run the tool, bring the window to the foreground and press Ctrl+Alt+S. The tool will create a file on your desktop called `window_styles.txt` with the information about the window.
+
+## Collected information
+
+* Process name
+* Window class
+* Window style parameters
+* Window exStyle parameters
+* DWM attributes
+* Infos about the Virtual Desktop the window is on

doc/devdocs/tools/verification-scripts.md

@@ -0,0 +1,26 @@
+# [Verification Scripts](/tools/Verification%20scripts/)
+
+This folder contains powershell scripts that help verifying the PowerToys installation.
+
+## [Check preview handler registration](/tools/Verification%20scripts/Check%20preview%20handler%20registration.ps1)
+
+This script checks the preview handler registration for the following file types:
+
+* .markdown
+* .mdtext
+* .mdtxt
+* .mdown
+* .mkdn
+* .mdwn
+* .mkd
+* .md
+* .svg
+* .svgz
+* .pdf
+* .gcode
+* .bgcode
+* .stl
+* .txt
+* .ini
+
+The tool shows the user handler and the machine handler for each file type and displays the App GUID of the corresponding handler.