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
```powershell
# 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? |