xetup/CLAUDE.md

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

---

Communication

• Communicate with the user in Czech
• Code, comments, log messages: English only (no diacritics rule still applies)

---

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