# ADR 0009: Mango + DankMaterialShell desktop option - **Status:** Accepted - **Date:** 2026-09-21 ## Context Phoebus's flagship desktop is a hand-assembled dwl session (dwl, waybar, wofi, mako, swaybg, swayidle, swaylock, polkit-gnome). It is lightweight and proven, but it requires the user to assemble everyday desktop functions. Mango (`gui-wm/mangowm`, a wlroots dwl derivative) plus DankMaterialShell (DMS, a Quickshell shell providing panel, launcher, notifications, network/Bluetooth/ audio controls, locking, idle and display management) is a complete, coherent desktop that fits the Wayland/systemd/PipeWire architecture. The task is to offer it as an explicit profile, keep dwl as a fallback, and promote Mango to the default only after verification. ## Upstream and packaging facts (verified 2026-09-21) | Component | Package | Version | Source | License | Keyword | |-----------|---------|---------|--------|---------|---------| | Compositor | `gui-wm/mangowm` | 0.17.2 | GURU (community) | CC0-1.0 / GPL-3+ / MIT | `~amd64` | | Shell | `gui-apps/dankmaterialshell` | 1.5.3 | GURU (community) | MIT | `~amd64` | | Framework | `gui-apps/quickshell` | 0.3.1 | GURU (community) | LGPL-3 | `~amd64` | | Search | `gui-apps/danksearch` | 0.3.2 | GURU (community) | MIT | `~amd64` | | Effects lib | `gui-libs/scenefx` | 0.5 | GURU (community) | MIT | `~amd64` | - `mangowm` depends on the **wlroots 0.20 slot** and `scenefx:0.5`. - `gui-wm/dwl` (the fallback) depends on the **wlroots 0.18 slot**. The two are different slots, so dwl and mangowm install side by side without a forced wlroots upgrade. - DMS is installed from DMS's **released** tarballs (its ebuild `SRC_URI` points at GitHub release assets); no live/git package is used. - GURU is git-only, so `dev-vcs/git` is installed from the main tree before the overlay is synced. - Upstream (Quickshell/DMS) requires Qt 6.6+, which the selected `default/linux/amd64/23.0/desktop/systemd` profile provides. ## Decision 1. **A new explicit profile** `desktop.profile = "mango"` installs Mango + DMS and *also* the dwl session as a fallback. Legacy values (`none`, `minimal`, `dwl`, `full`) keep their exact meaning. 2. **Portage owns the stack.** The installer writes `repos.conf` for GURU (git), installs `dev-vcs/git`, syncs GURU with `emaint sync -r guru`, and installs the packages with `emerge`. There is no `curl | sh`, no Nix, and no live package. 3. **Testing keywords are scoped.** `package.accept_keywords/phoebus` lists only `gui-wm/mangowm`, `gui-apps/dankmaterialshell`, `gui-apps/danksearch`, `gui-apps/quickshell` and `gui-libs/scenefx`. `~amd64` is never enabled globally, and Portage is not silently auto-unmasked: additional `~amd64` dependencies must be reviewed and added deliberately. 4. **Two session entry points, one shell each.** `/usr/share/wayland-sessions` gets `phoebus-mango.desktop` (default when the Mango profile is installed) and `phoebus-dwl.desktop` (fallback). The Mango session starts *only* mango, DMS (panel, launcher, notifications, lock, idle), and the shell's polkit agent; it never starts waybar/mako/swaybg/swayidle/swaylock. The dwl session is unchanged. 5. **User configuration is separate from packaged defaults.** The session seeds `~/.config/mango/config.conf` from `/etc/xdg/mango/config.conf` only when absent, and DMS manages `~/.config/mango/dms/*.conf`. Portage upgrades never overwrite user files. 6. **Administration stays behind `sys`.** DMS's system-update controls are not wired up; updates continue through `sys`/Portage. The assistant is reachable from a launcher (`phoebus-assistant`) that simply runs `sys ask`, keeping the typed-action and approval boundary. 7. **Default promotion is gated on verification.** Until the graphical-VM gates in `docs/VM-BOOT-VERIFICATION.md` pass, the Mango profile is *selectable*, not the default; `desktop.profile = "dwl"` remains the recommended default. ## Update procedure GURU is synced by `emaint sync -r guru` on every Portage sync. To move to a new upstream release, bump the reviewed versions in the keyword list only after `emerge --pretend` confirms the dependency set, then rebuild the profile's packages. The overlay is community-maintained; its ebuilds are attributed to their maintainers (see each `metadata.xml`). ## Consequences and risks - The Mango install pulls Qt, Quickshell and scenefx, so it is much heavier to build than the dwl session; a matching signed binhost does not exist for these GURU packages, so they compile. - GURU is a community overlay: provenance is documented but it is not the main Gentoo tree. The keyword scope keeps the risk limited to the listed packages. - DMS is a fast-moving project; the integration pins a reviewed release and documents the update path rather than tracking `9999`. - If DMS's polkit integration does not cover every prompt, a fallback `PHOEBUS_POLKIT_AGENT` hook is available but defaults off to avoid two agents. ## Verification status Unit and source-level tests cover the profile, package set, keyword scope, generated session scripts, config seeding and the two session entries. The graphical-VM acceptance gates (real seat, launcher/panel/notifications/polkit, lock/unlock, shell restart, logout cleanup, suspend/resume, Flatpak portals, idle/memory under load) are **not yet passed**; the profile therefore stays selectable and is not promoted to default. See `docs/STATUS.md`.