CLAUDE.md - Instructions for Claude Code

Project context

MSP deployment script for X9.cz - automated preparation of new Windows 10/11 computers for clients. Replaces ~3 hours of manual setup with a single PowerShell script.

Key parameters:

Target OS: Windows 10 and Windows 11 (x64), including unsupported HW
Execution: as Administrator on already-installed Windows (not WinPE/autounattend)
Volume: ~20 machines per month, various clients
Operator: MSP technician on-site at client

Repo structure

windows-deployment/
├── CLAUDE.md                     <- this file
├── SPEC.md                       <- technical specification
├── Deploy-Windows.ps1            <- master script (entry point)
├── scripts/
│   ├── 01-bloatware.ps1          <- remove AppX, Capabilities, Features
│   ├── 02-software.ps1           <- winget installs + Adobe PDF default
│   ├── 03-system-registry.ps1    <- HKLM tweaks
│   ├── 04-default-profile.ps1    <- C:\Users\Default\NTUSER.DAT changes
│   ├── 05-personalization.ps1    <- colors, wallpaper, theme
│   ├── 06-scheduled-tasks.ps1    <- register scheduled tasks
│   └── 07-desktop-info.ps1       <- custom desktop info (replaces BackInfo)
├── config/
│   └── config.json               <- per-client config (future)
├── assets/
│   └── DesktopInfo/              <- resources for desktop info script
└── tests/
    └── Test-Deployment.ps1       <- post-deployment verification

Conventions and rules

PowerShell

Always #Requires -RunAsAdministrator in master script
$ErrorActionPreference = "Continue" - script must survive partial failures
Log every step to C:\Windows\Setup\Scripts\Deploy.log
Logging via Write-Log function defined in master script
Invoke-Step function wraps every step - catches errors, logs, continues
Comments in English, code in English
NO diacritics - no accented characters anywhere: not in comments, not in user messages, not in log output
NO emoticons - not in comments, not in output messages
Reason: encoding issues across systems, log readability, compatibility

Master script structure

# 1. Load config.json
# 2. Run individual scripts in order
# 3. Print summary report at end (OK/ERROR counts)

Master script switches

Switch	Behavior
`-SkipBloatware`	Skip step 1
`-SkipSoftware`	Skip step 2
`-SkipDefaultProfile`	Skip step 4
`-DryRun`	Run without changes, log only

Testing

Test VM: Windows 10/11 x64 on VMware ESXi (X9.cz internal infrastructure)
Before each test: take snapshot
After test: revert snapshot
Dev environment: x64 VM only - NOT ARM (no Parallels/Apple Silicon for testing)

Important notes

BackInfo replacement - custom solution

BackInfo.exe is NOT used. Instead: custom scheduled task DesktopInfo:

Triggers on every user logon
PS script reads: hostname, IP, Windows version, username, install date
Renders text onto desktop via WPF/System.Drawing -> saves as BMP -> sets as wallpaper
Works on Win10 and Win11 without registry hacks

Adobe Reader as default PDF app

After install: set .pdf -> AcroRd32 association
Scheduled task PDF-DefaultApp restores association on every logon (guard against Edge overwriting it)

Default Profile

Changes to C:\Users\Default\NTUSER.DAT via reg load / reg unload
Applies to all new users - critical for MSP deployment
Currently logged-in user gets changes via direct write to HKCU

Winget

Always use --accept-package-agreements --accept-source-agreements
Check winget availability before running installs
Log result of every install

DO NOT

Do not use $ErrorActionPreference = "Stop" - script must survive partial failure
Do not remove Calculator (Microsoft.WindowsCalculator) - intentionally kept
Do not use ARM VM for testing
Do not write scripts depending on specific username - script is universal
Do not use hardcoded paths that do not exist on clean Windows
NO diacritics - no accented characters in any part of any script
NO emoticons - none in comments, log messages or output

Open questions

#	Question	Status
1	BackInfo replacement	DONE - custom PS scheduled task DesktopInfo
2	Complete SW list for winget	TODO - list incomplete
3	Per-client variability via config.json	FUTURE
4	Admin account adminx9 - script or manual?	OPEN

4.5 KiB Raw Blame History