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 (evolving toward Go TUI launcher).

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

---

Communication

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

---

Repo structure

windows-deployment-new/
├── CLAUDE.md                     <- this file
├── SPEC.md                       <- technical specification
├── Deploy-Windows.ps1            <- master script (entry point)
├── scripts/
│   ├── 00-admin-account.ps1      <- create hidden admin account
│   ├── 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       <- TO BE DELETED (replaced by BackInfo)
│   └── 08-activation.ps1         <- Windows activation via slmgr
├── config/
│   └── config.json               <- per-client config
├── assets/
│   ├── Backinfo/                  <- BackInfo.exe + .ini + backinfo_W11.ps1
│   └── Logo/                      <- X9-ikona.ico, X9-logo.jpeg
└── 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 (replaces custom DesktopInfo)

BackInfo.exe IS used. Located in assets/Backinfo/. Deployment:

1. Copy assets/Backinfo/ to C:\Program Files\Backinfo\
2. Run backinfo_W11.ps1 (detects OS, writes registry, creates Startup shortcut)
3. BackInfo.exe auto-starts on every logon, reads INI, renders BMP with system info

• Configurable via BackInfo.ini (fonts, positions, data sources)
• Displays: hostname (centered, large), username, OS, HW info, network info
• DELETE 07-desktop-info.ps1 - no longer needed

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)
• NOTE: UCPD.sys (kernel driver since Feb 2024) blocks UserChoice writes. Consider disabling UCPD during deployment.

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

Atera Agent

• Download: Invoke-WebRequest -Uri "https://x9.servicedesk.atera.com/api/utils/agent-install/windows/?cid=31&aeid=50b72e7113e54a63ac76b96c54c7e337" -OutFile setup.msi
• Install: msiexec /i setup.msi /qn

Admin account (adminx9)

• NO PASSWORD (changed from previous version)
• FullName = "X9.cz s.r.o." (via ADSI)
• Hidden from login screen
• Added to Administrators group

---

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
• Do not remove OneDrive - must remain installable for M365
• Do not remove RDP/RDS - must remain functional
• Do not remove Microsoft-RemoteDesktopConnection from Optional Features

---

Planned changes (from review v2, 2026-04-15)

Must fix

• Remove OneDrive uninstall from 03-system-registry.ps1 and 04-default-profile.ps1
• Remove password from admin account, add FullName = "X9.cz s.r.o."
• Delete 07-desktop-info.ps1, replace with BackInfo deployment step
• Add powercfg settings (standby-timeout-ac 0, monitor-timeout-ac 60, etc.)
• Add proxy auto-detect disable (AutoDetect = 0)
• Add Atera Agent install step
• Extend Edge policies (~15 more keys)

New features (from colleague spec v2)

• Taskbar pinned apps: admin vs user variants via XML layout + -ProfileType parameter
• Explorer: ShowRecent=0, ShowFrequent=0, FullPath=1 in CabinetState
• Network discovery: enable ping, set private network profile (post-restart step)
• PC rename: Rename-Computer as final step before restart
• C:\X9 directory structure with custom folder icon

Architecture evolution

• Go TUI launcher (xetup.exe) embedding PS scripts
• spec.yaml as single source of truth
• Web platform at xetup.x9.cz (Forgejo + docs + comments)
• Self-update mechanism in xetup.exe

---

Open questions

#	Question	Status
1	BackInfo replacement	DONE - using BackInfo.exe from assets/
2	Complete SW list for winget	TODO - list incomplete
3	Per-client variability via config.json	FUTURE
4	Admin account adminx9	DECIDED - no password, FullName "X9.cz s.r.o."
5	UCPD driver workaround for PDF default	TODO - disable during deployment
6	Atera MFA bypass	OPEN - does aeid parameter avoid MFA?