# veilor-os Installer

Branded TUI installer that runs on `tty1` of the live ISO. Wraps the
underlying `anaconda` kickstart install with a single-flow user experience
similar in spirit to `omarchy` and `archinstall`.

> **Status (v0.5.1):** TUI rewritten on top of [`gum`][gum] (charm.sh's
> Go TUI toolkit). Replaces the v0.5.0 `whiptail` build, which used the
> Fedora-default colors and looked out of place against the rest of the
> branded system.

## Screenshots

> _Placeholder — real screenshots to be captured against the v0.5.1 ISO
> once the gum-based installer ships and boots clean on test hardware._

| Stage          | Path                                  |
|----------------|---------------------------------------|
| Banner + menu  | `assets/installer/screenshots/01-menu.png`     _(TBD)_ |
| Disk picker    | `assets/installer/screenshots/02-disk.png`     _(TBD)_ |
| Confirm        | `assets/installer/screenshots/03-confirm.png`  _(TBD)_ |
| Install spin   | `assets/installer/screenshots/04-spin.png`     _(TBD)_ |

## Boot flow

```
power on
  └─ UEFI / GRUB
       └─ live kernel + initramfs
            └─ systemd → multi-user.target
                 └─ getty@tty1.service.d/veilor-installer.conf
                      └─ /usr/local/sbin/veilor-installer
                           ├─ source assets/installer/colors.gum
                           ├─ cat   assets/installer/banner.txt
                           └─ gum choose <main menu>
```

The override at `overlay/etc/systemd/system/getty@tty1.service.d/veilor-installer.conf`
replaces the standard login prompt on tty1 with the installer entry point.
Other ttys (2-6) still get a normal getty for recovery use.

## Main menu

| #  | Option                                      | Action                                     |
|----|---------------------------------------------|--------------------------------------------|
| 1  | Install veilor-os to disk                   | collect answers → generate ks → anaconda   |
| 2  | Try live — desktop (KDE Plasma)             | `systemctl isolate graphical.target`       |
| 3  | Try live — shell                            | `exec /bin/bash --login`                   |
| 4  | Reboot                                      | `systemctl reboot`                         |
| 5  | Power off                                   | `systemctl poweroff`                       |

## Install path — questions asked

In order, the installer collects:

1. **Target disk** (`gum choose` over `lsblk` output — selected disk is wiped)
2. **Hostname** (`gum input`, default `veilor`)
3. **LUKS passphrase** (`gum input --password`, min 8 chars, full-disk encryption)
4. **Admin password** (`gum input --password`, min 8 chars)
5. **Locale** (`gum choose` — en_GB, en_US, de_DE, fr_FR)
6. **Confirmation** (`gum confirm` — summary of choices before destructive step)

Answers are written into `/run/install/veilor-generated.ks` and handed off
to `anaconda --kickstart=...`. The kickstart inlines the LUKS passphrase
and the admin password — the file is _never_ committed and lives only in
the live tmpfs.

## Branding assets

| File                                | Purpose                                |
|-------------------------------------|----------------------------------------|
| `assets/installer/banner.txt`       | ASCII banner shown above the menu      |
| `assets/installer/colors.gum`       | sourceable bash file of GUM_* env vars |

The palette mirrors `assets/kde/veilor-black.colors`:
black `#000000` background, white `#FFFFFF` foreground, grey `#686B6F`
accent. No reds, no other colors. Pure monochrome.

## Logs

- `/var/log/veilor-installer.log` — installer stdout/stderr
- `/tmp/anaconda.log`             — kickstart execution log

Both are tee'd to the screen during the install spin, so a failed install
leaves visible breadcrumbs without forcing the user to dig.

## Credits & license

- [`gum`][gum] by [Charm](https://charm.sh) — MIT-licensed Go TUI toolkit.
  We dynamically `exec` gum at runtime; no source vendored. Distributed via
  the Fedora `gum` package.
- veilor-installer itself is MIT-licensed (see [LICENSE](../LICENSE)),
  matching the rest of the repo and the upstream gum project.

[gum]: https://github.com/charmbracelet/gum