121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# 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
|
|
```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 |
|