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