# SilverOS Welcome — Role App Recipes

> **Status**: design — 2026-06-09. Approved in brainstorming. Adds a per-role app-install
> picker to the first-logon Welcome wizard. Builds on the wizard in
> `windows/welcome/` and the flavour model in `windows/flavours/`.

## 1. Goal

Make the wizard's role/flavour selection *do something*: after choosing a role, the user
sees a grouped, pre-checked list of apps to install during onboarding — role-relevant tools
plus privacy-trimmed essentials — and the chosen apps are installed as part of Apply.

## 2. Decisions (locked in brainstorming)

- **Install engine: winget, phased.** v1 uses winget (`winget install --id <id> --silent`).
  IoT Enterprise LTSC ships *without* winget, so the engine bootstraps the App Installer at
  apply time. Every catalog app has a winget id. The catalog's per-app `source` object is
  **swappable** to a curated SilverMetal mirror later (the air-gap/privacy end-state) without
  changing the UI or engine contract.
- **Stack stays auto-installed.** The SilverLABS Stack (`SilverBrowser`=ungoogled-chromium
  rebrand, `SilverVPN`, `SilverKeys`, …) continues to install automatically via each flavour's
  `appSet` and is **not** in the picker (shown as "included"). The picker adds **role apps**
  plus **opt-in privacy-trimmed third-party** apps (incl. vanilla ungoogled-chromium and a
  Thunderbird email option).
- **Per-role lists + Essentials defaults** as in §4 (operator-approved; editable in the JSON).
- **WDAC caveat**: Developer/Daily-Driver run app-control in *audit* (apps run); Privacy-Max/
  Journalist run *enforce* (third-party apps blocked until allow-listed). v1 installs anyway and
  surfaces a clear note for enforce-mode roles; full WDAC allow-listing is a follow-up.

## 3. Architecture (four small units)

```
windows/apps/catalog.json            # the app catalog (staged into the image like flavours/)
SilverOS.Welcome.Core/Apps/
  AppCatalog.cs                       # record + loader (mirrors FlavourManifest)
  AppCatalogEntry.cs
  IAppInstaller.cs / AppInstaller.cs  # winget bootstrap + per-app install + configure
SilverOS.Welcome.UI/Components/Steps/
  AppsStep.razor                      # new wizard step: grouped checkboxes
WizardState.cs                        # + SelectedApps (ids)
ApplyService.cs                       # calls IAppInstaller after the Stack/hardening
```

### 3a. Catalog schema (`catalog.json`)
```json
{
  "schemaVersion": 1,
  "apps": [
    {
      "id": "vscodium",
      "name": "VSCodium",
      "description": "Telemetry-free VS Code build.",
      "source": { "winget": "VSCodium.VSCodium" },
      "group": "developer",
      "roles": ["developer"],
      "defaultFor": ["developer"],
      "configure": null
    },
    {
      "id": "ungoogled-chromium",
      "name": "ungoogled-chromium",
      "description": "Chromium with Google integration stripped.",
      "source": { "winget": "eloston.ungoogled-chromium" },
      "group": "essentials",
      "roles": ["essentials"],
      "defaultFor": [],
      "configure": "ungoogled-chromium.ps1"
    }
  ]
}
```
- `roles`: which roles are *offered* this app (`essentials` = all roles).
- `defaultFor`: roles where the checkbox is **pre-checked**.
- `source.winget`: the winget id (only `source` key in v1; a future `mirror` key is additive).
- `configure`: optional post-install script (relative to `windows/apps/configure/`), e.g. the
  ungoogled-chromium policy that enables the Chrome Web Store + sets safe search/suggestions.

### 3b. AppCatalog loader
Mirrors `FlavourManifest`/`IFlavourLoader`: `AppCatalogEntry` record + `AppCatalog.Load(dir)`
reading `catalog.json` with the same `JsonSerializerOptions` (case-insensitive, comments,
trailing commas). A pure function `AppsForRole(role)` returns the entries to display grouped,
and `DefaultSelectionForRole(role)` returns the pre-checked ids.

### 3c. AppsStep (new wizard step, after Flavour)
- Renders **Essentials** group first, then the chosen role's group; each app a checkbox with
  name + description; pre-checked from `DefaultSelectionForRole`.
- Writes the set of selected ids into `WizardState.SelectedApps`.
- Always valid (zero apps is allowed) — Next is never blocked. Notifies the host like the other
  steps (so Next state is correct immediately — same `OnSelected`/`StateHasChanged` pattern as
  the FlavourStep fix).
- `Routes.razor` gains a step between Flavour (1) and Account; step indices/titles shift by one.

### 3d. AppInstaller (Apply-step engine)
`IAppInstaller.InstallAsync(IReadOnlyList<AppCatalogEntry> apps, IProgress<ApplyProgress>, ct)`:
1. **Bootstrap winget** if absent: install `Microsoft.DesktopAppInstaller` + deps
   (`Microsoft.VCLibs…`, `Microsoft.UI.Xaml…`) via `Add-AppxProvisionedPackage`/staged msix.
2. **Per app**: `winget install --id <source.winget> --silent --accept-package-agreements
   --accept-source-agreements`; capture exit code; **continue on failure** (a bad app must not
   fail onboarding); run `configure` script if present and the install succeeded.
3. Return a per-app result list (id → installed/failed); ApplyService stows a summary for the
   Done step ("Installed N of M apps; failed: …").

Runs **after** hardening + Stack + accounts, **before** BitLocker (so encryption is last), via a
new `progress.Report(new("Installing apps", …))` stage.

## 4. Catalog contents (v1 — editable)

| Group | App | winget id | default-checked for |
|---|---|---|---|
| essentials | Thunderbird | `Mozilla.Thunderbird` | all |
| essentials | VLC | `VideoLAN.VLC` | all |
| essentials | 7-Zip | `7zip.7zip` | all |
| essentials | LibreOffice | `TheDocumentFoundation.LibreOffice` | all |
| essentials | ungoogled-chromium | `eloston.ungoogled-chromium` | — (opt-in; configured) |
| essentials | KeePassXC | `KeePassXCTeam.KeePassXC` | — |
| developer | VSCodium | `VSCodium.VSCodium` | developer |
| developer | Git | `Git.Git` | developer |
| developer | .NET 9 SDK | `Microsoft.DotNet.SDK.9` | developer |
| developer | Node.js LTS | `OpenJS.NodeJS.LTS` | developer |
| developer | Windows Terminal | `Microsoft.WindowsTerminal` | developer |
| developer | PowerShell 7 | `Microsoft.PowerShell` | developer |
| developer | Claude Desktop | `Anthropic.Claude` | developer |
| developer | Visual Studio 2022 | `Microsoft.VisualStudio.2022.Community` | — |
| developer | JetBrains Rider | `JetBrains.Rider` | — |
| developer | Docker Desktop | `Docker.DockerDesktop` | — |
| developer | Claude Code (CLI) | *(npm `@anthropic-ai/claude-code`, needs Node)* | — |
| developer | Google Chrome | `Google.Chrome` | — |
| developer | PostgreSQL | `PostgreSQL.PostgreSQL` | — |
| developer | Bruno (API client) | `Bruno.Bruno` | — |
| journalist | VeraCrypt | `IDRIX.VeraCrypt` | journalist |
| journalist | KeePassXC | `KeePassXCTeam.KeePassXC` | journalist |
| journalist | Joplin | `Joplin.Joplin` | journalist |
| journalist | OBS Studio | `OBSProject.OBSStudio` | — |
| journalist | Standard Notes | `StandardNotes.StandardNotes` | — |
| journalist | Signal | `OpenWhisperSystems.Signal` | — |
| journalist | Tor Browser | `TorProject.TorBrowser` | — |
| daily-driver | Spotify | `Spotify.Spotify` | — |
| daily-driver | Zoom | `Zoom.Zoom` | — |
| daily-driver | Discord | `Discord.Discord` | — |
| privacy-max | VeraCrypt | `IDRIX.VeraCrypt` | — |

> Claude Code (CLI) installs via npm, not winget — modelled with a `source.npm` variant the
> engine handles separately (and only if Node is selected/present). Listed but lower priority.

## 5. Build wiring
- `build.ps1`: stage `windows/apps/` (catalog.json + configure/) into the image
  (`C:\Program Files\SilverOS\Welcome\apps\` next to the flavours), same as flavours.
- The Welcome app reads the catalog from `AppContext.BaseDirectory\apps\catalog.json`.

## 6. Error handling
- Catalog missing/!parse → the Apps step shows an empty/"no extra apps" state and onboarding
  continues (never blocks).
- winget bootstrap fails (offline) → log it, skip the install stage with a Done-step note;
  onboarding still completes.
- Per-app install failure → recorded, surfaced in the Done summary, never throws.

## 7. Testing
- `AppCatalog` deserialization + `AppsForRole`/`DefaultSelectionForRole` unit tests (xUnit).
- `AppInstaller` against a fake `IProcessRunner`: asserts winget-bootstrap when absent, the exact
  `winget install` invocation per selected app, continue-on-failure, and configure-script run.
- `AppsStep` selection/validity (bUnit, matching the existing step tests' style).

## 8. Out of scope (follow-ups)
- Curated SilverMetal mirror (the `source.mirror` end-state) + signing for WDAC-enforce.
- WDAC allow-listing of installed apps for Privacy-Max/Journalist enforce mode.
- Per-app version pinning / update policy.