# ADR 0010: Graphical installer frontend and typed bridge - **Status:** Accepted - **Date:** 2026-09-21 ## Context The installer ISO boots into Mango + DankMaterialShell, but the only installer frontend was the ratatui TUI inside a terminal. The product direction makes installation the ISO's primary purpose: a welcoming, branded entry point and a coherent graphical setup flow. The core requirement is that the graphical frontend must not duplicate installation logic or scrape terminal output; the existing `InstallConfig`, plan, validation, orchestration and executor remain the single source of truth. ## Options considered 1. **A separately compiled Qt/QML application.** Requires shipping and building more Qt tooling and a non-trivial C++ or Rust/Qt binding layer. 2. **A Quickshell configuration.** Quickshell is already present (DMS is a Quickshell configuration) and provides windows plus process/socket I/O. A configuration is plain QML and needs no extra packages. 3. **A terminal TUI only.** Rejected: it is the fallback, not the welcome. ## Decision 1. **Quickshell/QML is the graphical frontend**, because it is the desktop's existing stack, is already in the live ISO, and needs no new package or build step. There are two configurations: `phoebus-welcome` (the live welcome and launcher) and `phoebus-install` (the wizard). The TUI/CLI remains a working fallback and is selected when Quickshell or Wayland is unavailable. 2. **A narrow, typed JSON bridge is the only interface.** A hidden `phoebus-installer --gui-bridge` mode reads newline-delimited JSON requests on stdin and writes typed JSON responses and progress events on stdout. The operations are bounded: `handshake`, `disks`, `set_config`, `set_secrets`, `validate`, `plan`, `destructive_preview`, `ai_check`, `approve`, `start_install`, `log_tail`, `quit`. Unknown ops and unknown request fields fail closed. 3. **The bridge reuses the audited backend.** It constructs the same `Installer` and calls `Installer::install_observed`, so the graphical install executes the identical stages, in the same order, with the same `DestructiveAuthorization` produced by the existing `authorize` flow. A progress observer (a small trait added to the orchestrator) reports the real stage transitions; categories name downloads, compilation, configuration and verification. No percentage is ever estimated. 4. **Approval is bound to the plan.** `approve` records a SHA-256 digest of the configuration plus the step sequence. `start_install` refuses unless the presented digest still matches the current plan, so any change — including an AI-applied change — invalidates a previous approval and forces a re-review. 5. **Secrets go over the stdin pipe, never argv, config or logs.** The GUI sends the LUKS passphrase, user password and API key through `set_secrets`; the bridge registers them with the redactor immediately and reports only presence. The model never receives them. 6. **The frontend is unprivileged.** It runs as the live user and starts the bridge with `/usr/bin/sudo -n`; only the bridge process holds privilege, and it exposes no shell. 7. **Live-only and installed surfaces stay separate.** The welcome window, its autostart and the "Install Phoebus OS" desktop entry are installed only on the live medium (gated by `/etc/phoebus/live`). The installed desktop has no reinstall shortcut. Upstream DMS first-run dialogs are suppressed on the live medium by pre-seeding DMS's own "already welcomed" marker files. 8. **A reusable brand system.** `phoebus-core::brand` defines charcoal, warm white and restrained amber tokens plus a sun emblem, wordmark and wallpaper as deterministic SVG, emitted through the existing `--emit-asset` plumbing and applied to the boot menu, wallpaper, welcome window, installer and icons. A test pins the QML palette to the Rust tokens. ## Consequences - The frontend cannot diverge from the backend: the protocol is the contract and the backend is unchanged. - The bridge and its protocol are fully unit-testable (dry-run) on any host; the QML is exercised in the disposable graphical VM. - The recovery-boot default bug exposed during GUI testing was fixed at the source: `loader.conf` now pins the newest real kernel entry, and the snapshot recovery entry carries a sort-key that keeps it last, so a low machine-id can never make the installed system boot into recovery. - A new frontend means ongoing QML maintenance; it is deliberately small. ## Verification Unit tests cover the protocol, validation wiring, approval binding, approval invalidation after a config change, blocked AI prerequisite, secret non-disclosure, readiness facts and the installed dry-run stage sequence. The GUI journey and a real install + detached boot are verified in the disposable VM (`docs/VM-BOOT-VERIFICATION.md`).