choosing a desktop installed seventy packages nobody had written down

`desktop = "niri"` lands about seventy packages a declaration never names,
and until now the only way to see them was `kuma generate`, which prints
them as one 900-character dnf line inside a 134-line Containerfile. The
reasoning was in better shape but worse placed: it lives in comments in
containerfile.rs, where no one running kuma will ever read it.

docs/desktops.md is the page that was missing. It does not try to be the
inventory. `kuma generate` is the authority for that and is named as
such in the first paragraph, because a hand-maintained list of seventy
packages drifts within a week and buying accuracy with churn is a bad
trade.

What the page has instead is the part no command can emit. Which layer
owns what, since an image is Fedora's minimal core, then kuma's base,
then the desktop, and only the last two are kuma's curation. The line
between infrastructure and applications, which existed as a rule but was
written down nowhere a user could see. Why COSMIC's set is a third the
size, because cosmic-session hard-requires a coherent desktop while niri
requires nothing beyond itself. And the members whose presence looks
arbitrary and is not: gnome-keyring-pam, nss-mdns,
zram-generator-defaults, glibc-langpack-en, the Vulkan pair, the Brands
font face, CJK. Every one of those was a failure someone diagnosed, and
the diagnosis was recorded in a source comment and nowhere else.

It also says plainly that you can add but cannot subtract, that there is
no rpm_exclude, and that disliking Thunar costs a fork. That is a real
limit and it belongs next to the list rather than being discovered.

concepts.md carries the principle in eight lines, since it is a
behaviour and belongs beside the other behaviours; the page carries the
enumeration. That split also contains the staleness: only one file holds
anything a package change can invalidate.

The test pins the nine explained packages in both directions, still in
the sets and still explained. Its first version was nearly worthless and
sabotage is what showed it: searching the whole page passed even with an
explanation deleted, because every package is also named in the
inventory table, so the assertion held exactly when the thing it guards
had been removed. It now searches only the section that explains. Both
directions verified by sabotage. 134 tests, fmt and clippy clean.

Author: Letdown2491

README.md

@@ -167,6 +167,9 @@ not obvious from them:
   than an error, what `kuma.lock` pins and what it only records, how
   `/etc` is merged rather than replaced, and how a bad update rolls itself
   back.
+- [What a desktop contains](docs/desktops.md): what `desktop = "niri"` or
+  `"cosmic"` installs that you didn't name, why the surprising parts are
+  there, and what you can change.
 - [For agents](docs/agents.md): the JSON surface, and why every response
   ends at the legal next commands.
 - [Contributing](CONTRIBUTING.md): smoke tests, booting a VM, iterating

docs/concepts.md

@@ -81,6 +81,19 @@ Two consequences:
 
 Naming a `base` opts out of all of it: any bootc image can be one.
 
+## A desktop is infrastructure, your declaration is applications
+
+Choosing a desktop installs packages you did not name. That set is session
+infrastructure: the parts that have to exist for a session to function.
+Applications are not in it, even convenient ones, because the two are
+reversible in different ways. Delete a line from your declaration and the
+next convergence uninstalls it; a package in a desktop set has no opt-out,
+so putting one there is a decision you make on behalf of everyone.
+
+You can always add with `packages.rpm`. You cannot subtract from the set.
+[What a desktop contains](desktops.md) lists both arms, explains the
+non-obvious members, and says where that limit bites.
+
 ## kuma.lock
 
 `base = "…/fedora-bootc:44"` names a tag, and tags move. One such move,

docs/desktops.md

@@ -0,0 +1,114 @@
+# What a desktop contains
+
+Setting `desktop = "niri"` or `desktop = "cosmic"` installs a set of packages
+you did not name. This is what lands, and what you can do about it.
+
+For the exact list any declaration produces, run `kuma generate` and read the
+`dnf install` line. That is the authority; this page explains it.
+
+## Three layers, two owners
+
+An image is built in layers, and they are not all curated by the same hand:
+
+1. **Fedora's minimal bootc core.** Kernel, systemd, bootc, dnf. Fedora
+   maintains it; kuma includes it unmodified.
+2. **kuma's base.** Networking, firmware, and the handful of things any real
+   machine needs: `shadow-utils`, `sudo`, `chrony`, `openssh-server`,
+   `passwd`, `cryptsetup`, `fwupd`. See
+   [the base is composed, not inherited](concepts.md#the-base-is-composed-not-inherited).
+3. **The desktop set.** Everything below.
+
+## The line between a desktop and your declaration
+
+A curated desktop is session infrastructure: the parts that have to be present
+for a session to function at all. Applications are not in it. A calculator, an
+office suite, a media player, or a store belongs in `packages.flatpak` in your
+declaration, even when it would be convenient to bake one in.
+
+The reason is reversibility rather than taste. A line in your declaration is a
+suggestion: delete it and the next convergence uninstalls it. A package in a
+desktop set is a decree, because there is no way to remove one (see
+[what you can change](#what-you-can-change) below). Being opinionated in an
+example declaration costs nothing. Being opinionated in the desktop set costs
+you a fork.
+
+## niri
+
+Hand-assembled, because niri is a window manager rather than a desktop: it
+requires nothing beyond itself, so every part of a working session is named
+explicitly.
+
+| | |
+|---|---|
+| Session | `niri`, `xwayland-satellite`, `greetd`, `tuigreet` |
+| Shell | `waybar`, `fuzzel`, `mako`, `wob`, `swaybg`, `swayidle`, `swaylock` |
+| Terminal and files | `kitty`, `thunar` (+ archive plugin), `file-roller`, `gvfs`, `udiskie`, `7zip`, `unar` |
+| Portals | `xdg-desktop-portal-gtk`, `xdg-desktop-portal-gnome` |
+| Audio | `pipewire`, `pipewire-pulseaudio`, `wireplumber`, `pavucontrol` |
+| Graphics | `mesa-dri-drivers`, `mesa-vulkan-drivers`, `vulkan-loader` |
+| Hardware | `NetworkManager-wifi`, `wpa_supplicant`, `bluez`, `blueman`, `brightnessctl`, `power-profiles-daemon` |
+| Printing and discovery | `cups`, `system-config-printer`, `avahi`, `nss-mdns` |
+| Screen and clipboard | `grim`, `slurp`, `swappy`, `wf-recorder`, `wl-clipboard`, `cliphist` |
+| Session glue | `polkit`, `mate-polkit`, `dconf`, `gnome-keyring`, `xsettingsd`, `xdg-user-dirs`, `firewalld`, `flatpak` |
+| Fonts | sans, mono, emoji, CJK, and Font Awesome (free and brands) |
+
+Graphical settings for wifi, bluetooth, audio, and printers are included on
+purpose. Those are machine state, not system definition: the declaration
+describes what a machine is, and picking a network is not that.
+
+## COSMIC
+
+Much shorter, because COSMIC curates itself. `cosmic-session` hard-requires
+the coherent desktop (compositor, panel, applets, settings, files, terminal,
+notifications, OSD, screenshot, portal, fonts), so kuma names the session plus
+the hardware enablement a desktop lives on, and little else.
+
+The additions worth knowing: `cosmic-edit`, because the default dock pins it
+and the session does not require it, so without it the pin is dead;
+`pipewire`, because the session requires the client library but nothing pulls
+the daemon; and `udisks2`, because `cosmic-files` mounts removable media
+through it directly.
+
+`cosmic-store` is deliberately absent. A store is an application, so which one
+a machine gets is the declaration's call.
+
+## Why these are here
+
+Most of a desktop set is unsurprising. These are not, and each one is a
+failure someone had to diagnose:
+
+- **`gnome-keyring-pam`** unlocks the login keyring at login. It is a separate
+  subpackage that nothing depends on, and the greeter's PAM lines are `-`
+  prefixed, so a missing module is skipped in total silence. Without it, login
+  succeeds, nothing is logged, and every keyring-using app prompts on launch
+  forever.
+- **`nss-mdns`** is what makes `.local` names and driverless printer discovery
+  actually resolve. `avahi` alone announces without resolving.
+- **`zram-generator-defaults`** carries the config that activates zram. The
+  base ships the generator without it, so the desktop would have zero swap and
+  the OOM killer would take windows under memory pressure.
+- **`glibc-langpack-en`** provides real locale data. The base ships
+  `glibc-minimal-langpack`, so `en_US.UTF-8` fails to resolve and waybar's
+  clock disables itself.
+- **`mesa-vulkan-drivers`** and **`vulkan-loader`**: OpenGL drivers alone
+  strand every Vulkan application on software rendering.
+- **`fontawesome-6-brands-fonts`** is a second font package because the
+  bluetooth glyph waybar uses lives in the Brands face, not Free.
+- **`google-noto-sans-cjk-vf-fonts`**, because the default sans is latin-only
+  and CJK pages render as tofu.
+- **`avahi`** is named rather than assumed. It used to arrive with
+  fedora-bootc by luck, and kuma's composed base does not carry it.
+
+## What you can change
+
+**You can add.** `packages.rpm` layers anything from Fedora's repos on top of
+the desktop set.
+
+**You cannot subtract.** There is no `rpm_exclude` and no per-desktop opt-out,
+so a package in a desktop set is in your image. If you want a desktop without
+Thunar, the only route today is a fork.
+
+That is a real limit rather than an oversight, and it is why the boundary above
+is drawn where it is: everything kuma cannot let you remove is something a
+session needs in order to work, and everything else is left to your
+declaration where deleting a line is enough.

src/containerfile.rs

@@ -2175,6 +2175,56 @@ mod tests {
     /// Native desktop ids look exactly like flatpak ids, so the handlers
     /// the desktop set installs are named here rather than inferred.
     /// Everything else in the list has to come from the declaration —
+    /// docs/desktops.md explains the desktop members whose presence is
+    /// not self-evident, and every one of them is a failure someone had
+    /// to diagnose: a silent keyring, a disabled clock, no swap, tofu.
+    /// Dropping one from the set while the page still explains it turns
+    /// the page into a lie about the image, and the reverse hides the
+    /// only written record of why the package is there at all.
+    ///
+    /// Only these are pinned, deliberately. The full inventory's home is
+    /// `kuma generate`, and asking a doc to track seventy packages would
+    /// buy drift in exchange for churn.
+    #[test]
+    fn the_surprising_desktop_packages_are_the_ones_documented() {
+        const EXPLAINED: &[&str] = &[
+            "gnome-keyring-pam",
+            "nss-mdns",
+            "zram-generator-defaults",
+            "glibc-langpack-en",
+            "mesa-vulkan-drivers",
+            "vulkan-loader",
+            "avahi",
+        ];
+        // niri-only: COSMIC's set has no waybar to lose its glyphs, and
+        // fonts follow the arm that renders with them.
+        const EXPLAINED_NIRI: &[&str] =
+            &["fontawesome-6-brands-fonts", "google-noto-sans-cjk-vf-fonts"];
+
+        let doc = std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/docs/desktops.md"))
+            .unwrap();
+        // Scoped to the section that does the explaining, not the whole
+        // page. Every package is also named in the inventory tables, so
+        // searching the file would assert only that the word appears
+        // somewhere, which stays true precisely when the explanation is
+        // the thing that got deleted.
+        let why = doc
+            .split_once("## Why these are here")
+            .and_then(|(_, rest)| rest.split_once("\n## "))
+            .map(|(section, _)| section)
+            .expect("docs/desktops.md explains the non-obvious members");
+
+        for pkg in EXPLAINED {
+            assert!(NIRI_PACKAGES.contains(pkg), "{pkg} left the niri set");
+            assert!(COSMIC_PACKAGES.contains(pkg), "{pkg} left the COSMIC set");
+            assert!(why.contains(pkg), "docs/desktops.md stopped explaining {pkg}");
+        }
+        for pkg in EXPLAINED_NIRI {
+            assert!(NIRI_PACKAGES.contains(pkg), "{pkg} left the niri set");
+            assert!(why.contains(pkg), "docs/desktops.md stopped explaining {pkg}");
+        }
+    }
+
     /// and the declaration to check is the niri one, because this file
     /// is only baked on the niri arm.
     #[test]