# SilverMetal WinPE Pre-Config Collector

> **Status**: design — 2026-06-10. Approved in brainstorming. Adds a branded WinPE
> collector that runs *before* Windows Setup, captures identity + install-shaping
> choices, generates the answer file so Setup creates the real account natively
> (eliminating the `sm-bootstrap` account + its teardown), and hands the rest to a
> simplified run-once-then-persist first-boot toolbox (the existing MAUI Welcome app,
> trimmed). Builds on `windows/installer/build.ps1`, `windows/installer/autounattend/`,
> and `windows/welcome/` (the MAUI wizard).

## 1. Goal

Let the user pre-configure the installation **before** the unattended installer runs.
A WinPE collector gathers **identity + install-shaping** choices, writes them into a
generated answer file (native account, computer name, locale, auto-logon) plus a
carried-forward config file (flavour, BitLocker PIN, app defaults). Windows Setup then
creates the real local administrator itself — so the first-boot app no longer creates
an account or removes a bootstrap user, and becomes a **config/toolbox**: it applies the
remaining post-install config once (apps, BitLocker), shows the recovery key, then
persists as a launchable tool.

## 2. Decisions (locked in brainstorming)

- **Collector scope = identity + install shaping.** It owns: the user **account**
  (display name, username, password), **computer name**, **locale/keyboard**,
  **flavour**, and the **BitLocker** choice + PIN. The toolbox owns **apps and ongoing
  config**; hardening runs headless via `SetupComplete.cmd` (see the last bullet).
- **Collector UI = PowerShell + WinForms.** WinPE cannot run the MAUI/WebView2 app (no
  Edge/Chromium, no modern .NET), so the collector is a separate, branded full-screen
  WinForms form. `WinPE-NetFx` + `WinPE-PowerShell` (and dependencies) are added to
  `boot.wim`.
- **Single real admin account.** One local **Administrators** account that the user
  defines — replacing both the ephemeral `sm-bootstrap` *and* today's "daily user +
  SilverOS Admin" split. (The two-account split can return later as a flavour option;
  out of scope here.)
- **Toolbox = run-once apply, then persist.** On first logon (as the real user) it
  auto-runs once, applies the collected config (apps, BitLocker PIN, flavour config),
  shows progress + the BitLocker recovery key, reaches Done — then stays installed as a
  launchable "SilverMetal" app. The heavy kiosk lockdown (Shell Launcher / Keyboard
  Filter / `sm-bootstrap` teardown) is dropped.
- **Handoff = generated answer file + embedded config (Approach 1).** Setup keeps owning
  the disk. The collector generates the answer file and embeds the non-OS config as
  base64 that a `specialize`-pass command writes to `C:` once it exists.
- **Hardening is canonical in SetupComplete.** Hardening runs headless from
  `SetupComplete.cmd` as SYSTEM (as the answer file already intends). The toolbox Apply
  focuses on **apps + BitLocker** — no duplicate hardening — so hardening is guaranteed
  even if the toolbox is closed. (A read-only hardening-status view in the toolbox is SP2.)

## 3. Architecture / flow

```
Boot ISO -> WinPE (boot.wim)
  winpeshl.ini -> SilverMetal Collector (PowerShell + WinForms)
     collects: account . computer name . locale . flavour . BitLocker PIN
     -> New-SmAnswerFile -> X:\sm\unattend.generated.xml  (embeds preconfig.json base64)
     -> setup.exe /unattend:X:\sm\unattend.generated.xml
Windows Setup:
  windowsPE pass : wipe disk0 (WillWipeDisk) -> install LTSC index 1 -> locale
  specialize pass: decode embedded preconfig.json -> C:\ProgramData\SilverMetal\preconfig.json
  oobeSystem pass: create REAL local admin -> AutoLogon(once) -> ComputerName
  SetupComplete.cmd (SYSTEM): hardening (canonical) + scrub C:\Windows\Panther\unattend.xml
First logon (real user, auto, once):
  Toolbox run-once -> read preconfig -> install apps + enrol BitLocker
     -> show recovery key -> Done -> clear PIN -> set "configured" marker
  Subsequent launches -> toolbox-home mode
```

## 4. Components

### 4a. WinPE collector (`windows/collector/`)
- **Launch**: `boot.wim` `winpeshl.ini` runs `X:\sm\Start-Collector.cmd` (instead of the
  default Setup shell), which calls `powershell -ExecutionPolicy Bypass -File X:\sm\Collector.ps1`.
- **UI** (`Collector.ps1`): a branded full-screen WinForms form (dark theme + SilverMetal
  logo) with fields:
  - Account: display name, username, password + confirm.
  - Computer name.
  - Locale / keyboard (defaults to today's en-GB / `0809:00000809`).
  - Flavour (the existing flavours, read from a small bundled list).
  - BitLocker: enable toggle + PIN + confirm (or skip).
  - A **"Use defaults"** fast path that fills sensible defaults so a user can click through.
- **Validation** (`Test-SmInput.ps1`, separated from the WinForms shell so it is
  unit-testable headless): username rules (non-empty, valid local-account chars, not a
  reserved name), password present + confirm-match (+ minimum length), PIN numeric +
  length (>= 6) + confirm-match when BitLocker enabled, computer-name rules
  (<= 15 chars, valid NetBIOS charset).
- **Output**: calls `New-SmAnswerFile` then launches Setup with the generated file.

### 4b. Answer-file generator (`windows/collector/New-SmAnswerFile.ps1`)
Pure function: collected values (a hashtable) -> answer XML string. Mirrors the current
`autounattend.xml` structure with these differences:
- **windowsPE**: keep `DiskConfiguration` (wipe disk 0, EFI/MSR/Primary) + `ImageInstall`
  index 1; locale from the collector.
- **oobeSystem**: emit **one** `LocalAccount` in `Administrators` (the user's
  account); `AutoLogon` Enabled with `LogonCount=1` as that user; `ComputerName`;
  `Microsoft-Windows-International-Core` locale; the existing `OOBE` hide-pages block.
  **No `sm-bootstrap`.**
- **specialize**: a `RunSynchronousCommand` that base64-decodes the embedded
  `preconfig.json` to `C:\ProgramData\SilverMetal\preconfig.json` (creating the dir).
- **FirstLogonCommands**: launch the toolbox elevated (as today, but as the real user).
- The **scrub** runs from `SetupComplete.cmd` (SYSTEM, end of Setup — guaranteed after
  account creation): it deletes `C:\Windows\Panther\unattend.xml` and the cached answer
  copy.

### 4c. `preconfig.json` contract
Written to `C:\ProgramData\SilverMetal\preconfig.json`:
```json
{
  "schemaVersion": 1,
  "flavour": "developer",
  "bitlocker": { "enable": true, "pin": "246810" },
  "apps": { "useFlavourDefaults": true }
}
```
- `flavour`: the chosen flavour id (drives the toolbox's app defaults + flavour config).
- `bitlocker.pin`: consumed by the toolbox to enrol TPM+PIN, then **the field is cleared**
  (rewritten without `pin`) once enrolment succeeds.
- `apps`: `useFlavourDefaults:true` (toolbox pre-checks the flavour defaults) or an
  explicit `selected: ["id", ...]` list (future: collector app picking — not in SP1; SP1
  always emits `useFlavourDefaults:true`).

### 4d. Simplified first-boot toolbox (`windows/welcome/`, trimmed)
- **Remove**: the Account step + `AccountService` account creation; `BootstrapService`
  `sm-bootstrap` teardown; the heavy kiosk lockdown (`Configure-Kiosk.ps1` Keyboard
  Filter / DisableTaskMgr / Shell Launcher path). Branding stays (baked offline; online
  re-apply unaffected).
- **Add**: a `PreconfigLoader` that reads `C:\ProgramData\SilverMetal\preconfig.json` and
  pre-seeds `WizardState` (flavour, app selection = flavour defaults, BitLocker PIN). On
  **first run** (no "configured" marker) the toolbox auto-applies: apps install +
  BitLocker enrol (using the preconfig PIN) + recovery-key display + Done; then it clears
  the PIN from preconfig and writes a `configured` marker
  (`C:\ProgramData\SilverMetal\configured`).
- **Apply pipeline** (trimmed): `apps -> bitlocker -> done`. No account step, no
  hardening (SetupComplete owns it), no teardown. Idempotent / re-runnable.
- **Persist**: the app stays installed with a Start-menu shortcut "SilverMetal".
  Subsequent launches (marker present) open **toolbox-home** (a simple landing page; rich
  ongoing-config surfaces are SP2).
- **Run mode selection**: marker present -> toolbox-home; marker absent + preconfig
  present -> first-run auto-apply; neither -> toolbox-home with flavour defaults
  (fail-open).

### 4e. `build.ps1` changes
- **Stage 2b (boot.wim servicing)**: in addition to forcing legacy Setup, add the WinPE
  optional components (`WinPE-NetFx`, `WinPE-PowerShell`, and their deps `WinPE-WMI`,
  `WinPE-Scripting`) via `Add-WindowsPackage`; copy `windows/collector/*` to the mounted
  boot.wim at `\sm\`; write `winpeshl.ini` to launch `\sm\Start-Collector.cmd`.
- **Fallback**: keep the static `autounattend.xml` on the ISO as the **default** answer
  file. The collector uses it as its template and as the fallback if cancelled. An env/marker
  `SM_UNATTENDED=1` (or a build flag) makes `Start-Collector.cmd` skip the UI and launch
  Setup with the static default — so **CI ISO builds remain non-interactive**.

## 5. Data flow / handoff

Single source of truth = the collector's captured values. From them:
- **OS-native fields** (account, computer name, locale, auto-logon) -> the generated
  answer file -> applied by Setup.
- **Non-OS config** (flavour, BitLocker PIN, app defaults) -> base64-embedded in the
  answer file -> written to `C:\ProgramData\SilverMetal\preconfig.json` in the
  `specialize` pass -> read by the toolbox.

No extra partition; Setup still owns disk partitioning (kept simplest + safest).

## 6. Error handling (must never brick boot)

- **Collector cancelled / crashes** -> launch Setup with the bundled **default** answer
  file (sensible defaults) so install still proceeds. The collector wraps its UI in
  try/catch and always has a path to Setup.
- **Generated XML fails validation** (schema/parse check before launch) -> use the
  default answer file.
- **`preconfig.json` missing / corrupt** at first boot -> toolbox proceeds with
  **flavour defaults** (fail-open, mirroring the app-catalog loader).
- **winget unavailable** -> already handled (graceful skip; PR #19).
- **BitLocker enrol fails** -> toolbox surfaces it but still reaches Done (apps/onboarding
  not blocked); PIN retained in preconfig only on failure so a re-run can retry.

## 7. Security

- **Local account only** (no Microsoft account / no cloud key escrow) — unchanged.
- **Account password** transits the generated answer file briefly; `SetupComplete.cmd`
  **scrubs `C:\Windows\Panther\unattend.xml`** (and the cached copy) after account
  creation.
- **BitLocker PIN** transits `preconfig.json`; the toolbox **clears it after enrolment**.
- **Residual (documented):** plaintext secrets exist transiently in WinPE memory and on
  the freshly-formatted disk until the scrub/clear runs. Acceptable for a local,
  operator-present install; a future hardening pass could DPAPI-wrap the PIN or prompt it
  interactively at first logon instead.

## 8. Testing

- **Pester — `New-SmAnswerFile`**: given inputs, the XML contains the real
  `LocalAccount` in Administrators, `AutoLogon` once as that user, the `ComputerName`,
  the locale, the `specialize` base64-write command, and the Panther scrub; and contains
  **no `sm-bootstrap`**. Base64 round-trips back to the original `preconfig.json`.
- **Pester — `Test-SmInput`**: username/password/PIN/computer-name validation rules
  (valid + each invalid case).
- **xUnit — toolbox `PreconfigLoader`**: parses a sample, fails open to flavour defaults
  on missing/corrupt, clears the PIN after a simulated enrol, honours the `configured`
  marker for run-mode selection.
- **`Assert-IsoStructure.ps1`**: boot.wim contains `winpeshl.ini` + `\sm\Collector.ps1`;
  WinPE-NetFx present (e.g. `Get-WindowsPackage` shows the package or a marker file); the
  toolbox payload no longer references `sm-bootstrap`.
- **VM e2e**: collector form renders in WinPE -> fill in account/flavour/PIN -> install ->
  first logon auto-applies (apps skipped if no network, BitLocker per env) -> recovery key
  shown -> Done -> relaunch shows toolbox-home.

## 9. Scope / phasing

- **SP1 (this spec):** WinPE collector (account, flavour, computer name, locale, BitLocker
  PIN) + answer-file generation + `preconfig.json` handoff + simplified run-once-then-persist
  toolbox; remove `sm-bootstrap` + account step + heavy kiosk; hardening canonical in
  SetupComplete.
- **SP2 (later):** rich toolbox-home — ongoing config surfaces (re-run/extend apps, change
  settings, view hardening status).
- **SP3 (later):** install-time disk target / partitioning + BitLocker pre-provisioning on
  the blank drive (the deferred "maximal" collector scope).

## 10. Out of scope (SP1)

- App selection inside the collector (SP1 emits `useFlavourDefaults:true`; the toolbox
  remains the place to pick apps).
- The two-account (daily + admin) split — SP1 is single admin.
- Disk target / partition UI; BitLocker pre-provision in WinPE.
- DPAPI-wrapping or interactive-at-first-logon secret handling (noted as a future
  hardening option in §7).