xetup/SPEC.md

# MSP Windows Deployment - Specification

> Purpose: Automated preparation of new Windows 10/11 computers for X9.cz clients

---

## Overview

xetup.exe replaces ~3 hours of manual computer setup. GUI launcher embeds PowerShell
scripts, runs them sequentially, handles reboot cycles, sends email report when done.
Settings are applied to Default Profile (NTUSER.DAT) so every new user inherits them.

---

## Prerequisites

- Windows 10 or Windows 11 (x64)
- Run as Administrator
- Internet connection (for winget installs, Atera agent, Windows Update)
- Post-OOBE (fully installed Windows with at least one user account)

---

## Step execution order

| # | Step | Script | Notes |
|---|---|---|---|
| 00 | Admin account | 00-admin-account.ps1 | adminx9, no password, hidden |
| 08 | Windows activation | 08-activation.ps1 | OA3 → config key → GVLK fallback |
| 01 | Bloatware removal | 01-bloatware.ps1 | AppX + Capabilities + Features |
| 02 | Software install | 02-software.ps1 | Parallel winget + Atera + PDF default |
| 03 | System registry | 03-system-registry.ps1 | HKLM tweaks, Edge, powercfg, WPAD |
| 04 | Profile + personalization | 04-default-profile.ps1 | NTUSER.DAT + HKCU + theme |
| 07 | BackInfo | 07-backinfo.ps1 | System info wallpaper overlay |
| 10 | Network | 10-network.ps1 | Private profile, ping, discovery |
| 11 | Dell Update | 11-dell-update.ps1 | Auto-skip on non-Dell HW |
| 09 | PC identity | 09-pc-identity.ps1 | Rename + C:\X9 (reboot on rename) |
| 12 | Windows Update | 12-windows-update.ps1 | Multi-round reboot cycle |

---

## Step 00 - Admin account

Creates local admin account `adminx9`:
- No password (empty) - account is hidden, only accessible to technicians
- FullName = "X9.cz s.r.o." (via ADSI)
- Added to Administrators group
- Hidden from login screen (SpecialAccounts\UserList = 0)
- Password never expires

---

## Step 08 - Windows activation

Priority: OA3 embedded key (BIOS/UEFI) → config.json productKey → GVLK by edition.
Optional KMS server via config.json. Skips if already activated (LicenseStatus = 1).

---

## Step 01 - Bloatware removal

Removes ~35 AppX packages (Cortana, Copilot, Teams, Xbox, Skype, News, etc.),
~14 Windows Capabilities (Fax, IE, WordPad, etc.), and Optional Features
(PowerShell 2.0, Recall). Calculator intentionally kept.

Three GUI feature toggles gate removal:
- `standardBloatware` (default on) - the bulk list above.
- `removeNewOutlook` (default on) - the new Outlook for Windows app
  (`Microsoft.OutlookForWindows`). Classic Outlook from M365 is a Win32 app and
  is never touched.
- `removeSnippingTool` (default OFF) - Snipping Tool across all three lists
  (ScreenSketch app + legacy capability + legacy feature). Kept by default as a
  common productivity tool, like Calculator.

---

## Step 02 - Software installation

Parallel winget installs (Start-Job). Every install uses `--source winget` to bypass the
msstore source, which fails on fresh Win11 ISOs (stale App Installer cert, 0x8a15005e):

| Software | Winget ID |
|---|---|
| 7-Zip | 7zip.7zip |
| Adobe Acrobat Reader 64-bit | Adobe.Acrobat.Reader.64-bit |
| OpenVPN Connect | OpenVPNTechnologies.OpenVPNConnect |

After Acrobat: UCPD driver stopped, .pdf → AcroExch.Document.DC set via HKCR, UCPD restarted.
On Win11 24H2 UCPD is a protected service and the stop fails (logged WARN, not ERROR); the
system-wide HKCR write succeeds regardless.

Atera RMM agent: downloaded from x9.servicedesk.atera.com, installed under NT AUTHORITY\SYSTEM
via a one-shot scheduled task (msiexec /qn). Under SYSTEM the agent registers silently with no
interactive MFA prompt. Verified via the AteraAgent service (Get-Service), with a path check
(incl. C:\ProgramData) as fallback.

---

## Step 03 - System registry (HKLM)

Always applied: password max age unlimited, timezone (Central Europe Standard Time).

Feature-toggled sections:
- **systemTweaks**: BypassNRO, disable Teams auto-install, Widgets, GameDVR, Recall, Copilot search,
  Smart App Control (VerifiedAndReputablePolicyState=0, permanent)
- **edgePolicies**: mandatory only (HideFirstRunExperience, DefaultBrowserSettingEnabled,
  DiagnosticData, FeedbackSurveysEnabled) + initial_preferences file for UI defaults
  (favorites bar, no home button, no search suggestions, clean NTP, no rewards/shopping/collections).
  initial_preferences is read by Edge once on first profile creation - user can override freely.
- **oneDriveUninstall**: removes consumer OneDrive (no policy block - M365 can reinstall)
- **powercfg**: hibernate off; standby-ac=0, monitor-ac=60, standby-dc=30, monitor-dc=15
- **proxyDisable**: WPAD auto-detect off

---

## Step 04 - Default Profile + Personalization

Single hive load of C:\Users\Default\NTUSER.DAT. All changes applied to both Default
hive and current HKCU. Feature-toggled sections:

- **taskbarTweaks**: left alignment, hide Search/Copilot/TaskView/Widgets/Chat, show all
  tray icons, taskbar layout XML per ProfileType (default/admin/user), NumLock on.
  File Explorer is pinned via its AppUserModelID (DesktopApplicationID="Microsoft.Windows.Explorer"),
  not a custom .lnk - a hand-made shortcut launched a second Explorer and could not be unpinned.
- **startMenuTweaks**: empty pins, disable Bing search, disable Copilot, disable GameDVR
- **explorerTweaks**: show extensions, LaunchTo=ThisPC, hide Recent/Frequent, full path

Keyboard (always): CZ primary + US secondary - Set-WinUserLanguageList (current user) plus
the Preload key (1=00000405 CZ, 2=00000409 US) in the Default hive and HKU\.DEFAULT.

Personalization (always): Custom mode (dark shell / light apps), accent #223B47 set via
AccentColor AND AccentPalette (the palette is required or Win11 drops the custom accent on
Start/taskbar), ColorPrevalence on for Start/taskbar and title bars/borders, transparency off,
solid wallpaper #223B47 (BackInfo overwrites on logon). Written to the Default hive (new users),
the current user (HKCU) and HKU\.DEFAULT (lock/welcome screen) so all profiles match.

---

## Step 07 - BackInfo

Copies BackInfo.exe + INI to C:\Program Files\Backinfo\. Detects OS, writes OSName to
registry. Creates startup shortcut for all users. BackInfo renders system info BMP as
desktop wallpaper on every logon. Background is solid #223B47 (BackInfo.ini
BackgroundColor = 4668194; BackInfo uses a COLORREF / 0x00BBGGRR / BGR value, so
#223B47 = 71*65536 + 59*256 + 34 = 4668194. The RGB value 2243399 rendered olive-brown).
Because BackInfo paints a centered bitmap, step 04 also sets the solid desktop background color
(#223B47) in the Default hive, the current user, HKU\.DEFAULT and every existing profile - otherwise
a sub-screen bitmap shows a black border around it.

---

## Step 10 - Network

Sets all connected adapters to Private profile. Enables ICMP echo (ping) and Network
Discovery firewall rules. Network Discovery is matched by its resource-string group
(-Group "@FirewallAPI.dll,-32752"), not the localized display name, so it works on
non-English (e.g. Czech) Windows.

---

## Step 11 - Dell Command | Update

Detects Dell hardware via Win32_ComputerSystem.Manufacturer. On non-Dell: skips silently.
On Dell: installs DCU Universal via winget, runs dcu-cli.exe /applyUpdates with
-reboot=disable. Feature-toggled: drivers/firmware and BIOS separately. Exit 9 when
BIOS/firmware updates are staged (finalize on next restart).

---

## Step 09 - PC identity

Creates C:\X9\ directory (Logs, Scripts, Assets) with custom folder icon.
Sets computer description. Renames computer if config.json pcName is set and differs
from current. Exit 9 only when rename actually happened (restart required).

---

## Step 12 - Windows Update

Installs PSWindowsUpdate module, runs one update pass. Exit 9 when updates were installed
(reboot needed for next round). Exit 0 when fully up to date. xetup state machine handles
the reboot cycle automatically. Installed updates are logged via their Result/Title
properties (logging the raw objects printed "System.__ComObject").

---

## Config structure

```json
{
  "deployment": { "pcName": "", "pcDescription": "", "timezone": "...", "profileType": "default" },
  "adminAccount": { "username": "adminx9" },
  "activation": { "productKey": "", "kmsServer": "" },
  "software": { "install": [{ "name": "...", "wingetId": "..." }] },
  "steps": { "adminAccount": true, ... },
  "features": { "bloatware": { "standardBloatware": true, "removeNewOutlook": true, "removeSnippingTool": false }, "software": { "wingetInstalls": true, ... }, ... },
  "bloatware": { "keepPackages": ["Microsoft.WindowsCalculator"] }
}
```

---

## Email report

Sent via SMTP2Go at end of deployment. HTML with per-step status table, timestamps,
OK/ERROR/SKIPPED counts. Subject: "xetup report HOSTNAME".
From: xetup@x9.cz, To: net@x9.cz.

---

## Code signing (CI)

The Forgejo Actions release workflow signs xetup.exe on every push to main (and via
workflow_dispatch): build → sign → publish. Signing uses Azure Trusted Signing (certificate
"X9.cz s.r.o.") through jsign, with an RFC3161 timestamp (timestamp.acs.microsoft.com).
Trusted Signing certs are short-lived (~3 days); the timestamp keeps the signature valid past
expiry. Only the Entra client secret is a Forgejo secret (AZURE_CLIENT_SECRET); the signed
binary is published as the "latest" release asset.