# mibook: choose terminal-only vs desktop at boot

## Goal

Let mibook offer a choice, each time it boots, between the normal KDE desktop
and a terminal-only ("server") mode with no graphical session — decided at
boot, without rebuilding the system.

## Background: why the first attempt failed

The first implementation booted mibook to a text console by default
(`systemd.defaultUnit = "multi-user.target"`, display manager not started) and
provided a `desktop` command to start KDE on demand. On real hardware this
locked the machine out:

- **No SSH.** mibook is WiFi-only and its WiFi credentials are stored per-user
  in KWallet ("agent-owned"). NetworkManager only receives the password once a
  desktop session is running, so a headless boot never joins the network and
  the machine has no IP — nothing to SSH into.
- **No usable console.** The boot appeared to "hang" with no login prompt:
  `NetworkManager-wait-online` stalled waiting for a network that never came
  up, and the `getty` login prompt on tty1 was buried under later service
  messages.

Conclusion: a headless WiFi laptop cannot be reached remotely, and the plain
console was hard to use. The design must (a) keep the desktop as the reliable
default, (b) make the terminal path a deliberate, self-sufficient choice, and
(c) not depend on the network being up.

## Behavior

- The **default GRUB entry** boots straight into KDE — unchanged from the
  known-working baseline.
- A **separate GRUB entry, `mibook (terminal)`** (a NixOS *specialisation*),
  boots to a text console with **autologin** for `finn`. From there the user
  can work in the shell or run `desktop` to bring KDE up (via SDDM).
- The choice is made in the GRUB menu at boot — matching the original request
  to "decide each time I boot."
- Booting never stalls on the network.

### Known limitation (documented, not fixed in config)

In terminal mode WiFi will not connect on its own, because the password is
stored per-user in KWallet. To reach mibook over SSH from terminal mode, the
user must first save the WiFi as a **system** connection in KDE:
network settings → the WiFi network → "All users may connect to this network".
Until then, terminal mode is local-console-only. This is a one-time manual
step outside the scope of the Nix config.

## Implementation

### `machines/mibook/configuration.nix`

- Add a NixOS specialisation `specialisation.terminal.configuration`:
  - `system.nixos.tags = [ "terminal" ];` — labels the generated boot entry.
  - `systemd.defaultUnit = lib.mkForce "multi-user.target";` — boots to the
    text console. `graphical.target` is what pulls in the display manager (via
    its embedded `Wants=display-manager.service`), so defaulting to
    `multi-user.target` leaves SDDM installed but not started at boot.
  - `services.getty.autologinUser = "finn";` — guarantees a usable shell on
    the console instead of a login prompt that can scroll off screen.
  - A `desktop` command via
    `pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service"`
    in `environment.systemPackages`, to start KDE on demand.
- Add `systemd.services.NetworkManager-wait-online.enable = false;` (applies to
  both the default and terminal boots) so boot never stalls waiting for the
  network.

### Reverted from the first attempt

- `modules/environments/kde-desktop/default.nix` — remove the `startOnBoot`
  option and its `mkMerge`/`mkIf` machinery; back to the original profile that
  simply enables SDDM + Plasma 6.
- `machines/mibook/environments.nix` — remove `kde-desktop.startOnBoot = false;`
  (back to just `kde-desktop.enable = true;`).

## Why a specialisation

A specialisation generates a second boot-menu entry automatically from a
modified copy of the configuration. It is the idiomatic NixOS mechanism for a
boot-time choice and avoids fragile hand-written GRUB `extraEntries` that would
need to track kernel/initrd paths across generations. The default entry remains
byte-for-byte the working desktop configuration.

## Testing / verification

- `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
  builds both `nixos-system-mibook` and `nixos-system-mibook-terminal`.
- Verified on the built closures:
  - Parent `default.target` → `graphical.target`; no console autologin
    (identical to the pre-change baseline).
  - Specialisation `default.target` → `multi-user.target`; tty1 getty wrapper
    contains `--autologin finn`; `desktop` present in the system profile.
  - `NetworkManager-wait-online` disabled in both.
- Post-`switch` manual check on mibook: default GRUB entry boots to KDE; the
  `terminal` entry boots to an autologged-in console; running `desktop` there
  starts SDDM and a working Plasma session.

## Trade-offs

- Autologin on the terminal console means physical access grants a shell
  without a password. Acceptable for a personal laptop the user controls; the
  desktop (default) boot is unaffected.
- `desktop` relies on `sudo`; the user has sudo access, so no extra config is
  required.