docs+test: ecosystem matrix, keybinds, limitations, recovery, smoke test

README: add a bread-ecosystem feature matrix, keyboard-shortcut reference,
a Known Limitations section (NVIDIA/Mesa, VM GPU accel, Secure Boot, btrfs
assumption), and a Recovery guide (snapshot rollback + GRUB/EFI repair from
the live ISO).

scripts/smoke-test.sh: read-only post-install validator — btrfs subvolumes,
snapper config, enabled services, bread bins on PATH, bos-settings, default
dotfiles, and the GRUB EFI artifacts. Exits non-zero on any failure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -118,6 +118,86 @@ cargo build --release -p bos-settings
 cargo test -p bos-settings        # includes config round-trip tests
 ```
 
+## The bread ecosystem at a glance
+
+| Tool | Role | Launch |
+|------|------|--------|
+| `bread` / `breadd` | Reactive automation daemon — normalises hardware/compositor signals into events dispatched to Lua modules | runs at login |
+| `breadbar` | Top status bar (workspaces, clock, stats, tray) **and** the notification daemon | runs at login |
+| `breadbox` | Application launcher | `SUPER+Space` |
+| `breadpad` | Notes & reminders (AI-classified, optional CalDAV sync) | `SUPER+U` |
+| `breadman` | Package-manager UI | `SUPER+M` |
+| `breadcrumbs` | Wi-Fi profile state machine (location-aware) | CLI / BOS Settings |
+| `bakery` | CLI package manager for the ecosystem | `bakery` |
+| `bos-settings` | Unified GTK4 control panel for all of the above + snapshots + updates | `SUPER+,` |
+
+## Keyboard shortcuts
+
+`SUPER` is the Windows/Cmd key. Press **`SUPER+/`** at any time for this
+cheatsheet in-session; first boot shows a short welcome (once).
+
+| Keys | Action |
+|------|--------|
+| `SUPER+Return` | Terminal (kitty) |
+| `SUPER+Space` | App launcher (breadbox) |
+| `SUPER+E` / `SUPER+B` | Files (nautilus) / Browser (zen) |
+| `SUPER+U` / `SUPER+M` | breadpad / breadman |
+| `SUPER+,` / `SUPER+/` | BOS Settings / keybind cheatsheet |
+| `SUPER+L` / `SUPER+N` | Lock / log out |
+| `SUPER+Backspace` | Close window |
+| `SUPER+F` / `SUPER+V` / `SUPER+T` | Fullscreen / float / toggle split |
+| `SUPER+Shift+V` | Clipboard history |
+| `SUPER+Tab` | Last window |
+| `SUPER+Shift+S/C/P` | Screenshot region→file / region→clipboard / screen→file |
+| `SUPER+arrows` | Move focus |
+| `SUPER+Shift+h/j/k/l` | Move window |
+| `SUPER+Shift+arrows` | Resize window |
+| `SUPER+1..0` | Switch to workspace 1–10 |
+| `SUPER+Shift+1..0` | Move window to workspace |
+| `SUPER+[ / ]` | Previous / next workspace |
+| `SUPER+left/right-drag` | Move / resize window with the mouse |
+
+## Known limitations
+
+- **GPUs**: ships the generic Mesa stack — AMD and Intel work out of the box.
+  The **NVIDIA proprietary driver is not included**; NVIDIA users must install
+  `nvidia`/`nvidia-utils` and set the usual Hyprland env vars after install.
+- **Virtual machines**: Hyprland needs GPU acceleration to be smooth. Use
+  `virtio-vga-gl` + `-display gtk,gl=on` (virgl); plain software rendering is
+  noticeably laggy.
+- **Wayland-first**: X11-only apps run through XWayland; a few may misbehave.
+- **Secure Boot**: not configured. Boot with Secure Boot disabled, or enroll
+  your own keys. The installer writes both an NVRAM entry and the removable
+  `EFI/BOOT/BOOTX64.EFI` fallback.
+- **Snapshots assume btrfs**: the snapper/grub-btrfs tooling expects the default
+  btrfs subvolume layout the installer creates.
+
+## Recovery
+
+**An update broke something (system still boots):** open BOS Settings →
+Snapshots and roll back, or pick a pre-update snapshot from the **GRUB
+“snapshots” submenu** at boot, then run `snapper rollback` from the booted
+snapshot.
+
+**The system won't boot (broken GRUB / lost EFI entry):**
+
+1. Boot the BOS ISO and open a terminal (`SUPER+Return`).
+2. Mount the installed root and EFI, then chroot:
+   ```sh
+   mount -o subvol=@ /dev/sdXN /mnt
+   mount /dev/sdXP /mnt/boot/efi      # the EFI partition
+   arch-chroot /mnt
+   ```
+3. Reinstall the bootloader (the same sequence the installer uses):
+   ```sh
+   grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=BOS --recheck
+   grub-install --target=x86_64-efi --efi-directory=/boot/efi --removable --recheck
+   grub-mkconfig -o /boot/grub/grub.cfg
+   ```
+
+**Firmware shows “no boot device”:** select `EFI/BOOT/BOOTX64.EFI` from the
+firmware boot menu — the installer always writes that removable fallback.
+
 ## Boot architecture notes
 
 archiso keeps the kernel and initramfs outside the squashfs, so the installer

iso/airootfs/etc/skel/.config/hypr/hyprland.lua

@@ -85,6 +85,12 @@ for _, animation in ipairs(animations) do
     hl.animation(animation)
 end
 
+-- ---------------------------------------------------------------------------
+-- Window rules — float + centre the onboarding popups (kitty --class …).
+-- ---------------------------------------------------------------------------
+hl.window_rule({ name = "bos-keybinds", match = { class = "^(bos-keybinds)$" }, float = true, size = { 760, 720 } })
+hl.window_rule({ name = "bos-welcome",  match = { class = "^(bos-welcome)$" },  float = true, size = { 700, 560 } })
+
 -- ---------------------------------------------------------------------------
 -- Environment (vendor-neutral; no GPU-specific vars so it works on Intel/AMD).
 -- ---------------------------------------------------------------------------
@@ -113,6 +119,8 @@ hl.bind(mod .. " + E",         hl.dsp.exec_cmd("nautilus"))
 hl.bind(mod .. " + B",         hl.dsp.exec_cmd("zen-browser"))
 hl.bind(mod .. " + U",         hl.dsp.exec_cmd("breadpad"))
 hl.bind(mod .. " + M",         hl.dsp.exec_cmd("breadman"))
+hl.bind(mod .. " + comma",     hl.dsp.exec_cmd("bos-settings"))
+hl.bind(mod .. " + slash",     hl.dsp.exec_cmd("bos-keybinds"))
 hl.bind(mod .. " + L",         hl.dsp.exec_cmd("loginctl lock-session"))
 hl.bind(mod .. " + F",         hl.dsp.window.fullscreen({ action = "toggle" }))
 hl.bind(mod .. " + V",         hl.dsp.window.float({ action = "toggle" }))
@@ -196,6 +204,8 @@ hl.on("hyprland.start", function()
         "breadbar",
         "breadbox-sync",
         "hypridle",
+        -- first-boot onboarding (self-gates after the first run)
+        "bos-welcome",
     }
     for _, cmd in ipairs(startup) do
         hl.dispatch(hl.dsp.exec_cmd(cmd))

iso/airootfs/usr/local/bin/bos-keybinds

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Show the BOS keybind cheatsheet in a floating terminal (bound to SUPER+/).
+# The bos-keybinds window class is floated/centred by a Hyprland window rule.
+exec kitty --class bos-keybinds --title "BOS Keybinds" -- less -R /usr/share/bos/keybinds.txt

iso/airootfs/usr/local/bin/bos-welcome

@@ -0,0 +1,15 @@
+#!/bin/bash
+# First-run welcome. Shows a short getting-started message once, then drops a
+# marker so it never shows again. Launched from the Hyprland autostart; the
+# bos-welcome window class is floated/centred by a Hyprland window rule.
+set -u
+
+# Never run in the live/installer session — only on an installed system.
+[[ "$(id -un)" == "liveuser" ]] && exit 0
+
+marker="${XDG_CONFIG_HOME:-$HOME/.config}/bos/.welcomed"
+[[ -f "$marker" ]] && exit 0
+mkdir -p "$(dirname "$marker")"
+touch "$marker"
+
+exec kitty --class bos-welcome --title "Welcome to BOS" -- less -R /usr/share/bos/welcome.txt

iso/airootfs/usr/share/bos/keybinds.txt

@@ -0,0 +1,50 @@
+
+   ██████   ██████  ███████      keyboard shortcuts
+   ██   ██ ██    ██ ██           SUPER is the Windows/Cmd key
+   ██████  ██    ██ ███████
+   ══════════════════════════════════════════════════════════
+
+   APPS & WINDOWS
+     SUPER + Return            terminal (kitty)
+     SUPER + Space             app launcher (breadbox)
+     SUPER + E                 files (nautilus)
+     SUPER + B                 browser (zen)
+     SUPER + U                 notes / reminders (breadpad)
+     SUPER + M                 package manager (breadman)
+     SUPER + ,                 BOS Settings
+     SUPER + /                 this keybind cheatsheet
+     SUPER + L                 lock screen
+     SUPER + Backspace         close window
+     SUPER + F                 fullscreen
+     SUPER + V                 toggle floating
+     SUPER + Shift + V         clipboard history
+     SUPER + T                 toggle split direction
+     SUPER + Tab               last window
+     SUPER + N                 exit Hyprland (log out)
+
+   SCREENSHOTS
+     SUPER + Shift + S         select region  -> file
+     SUPER + Shift + C         select region  -> clipboard
+     SUPER + Shift + P         whole screen   -> file
+
+   FOCUS & MOVE
+     SUPER + arrows            move focus
+     SUPER + Shift + h/j/k/l   move window
+     SUPER + Shift + arrows    resize window
+
+   WORKSPACES
+     SUPER + 1..0              switch to workspace 1..10
+     SUPER + Shift + 1..0      move window to workspace
+     SUPER + [ / ]             previous / next workspace
+     SUPER + Shift + [ / ]     move window prev / next workspace
+     SUPER + scroll            cycle workspaces
+
+   MOUSE
+     SUPER + left-drag         move window
+     SUPER + right-drag        resize window
+
+   MEDIA & HARDWARE KEYS
+     volume / brightness / play-pause / next / prev   (work on lock screen)
+
+   ──────────────────────────────────────────────────────────
+   Press q to close.  Configure everything in BOS Settings (SUPER + ,).

iso/airootfs/usr/share/bos/welcome.txt

@@ -0,0 +1,24 @@
+
+   Welcome to BOS — the Bread Operating System
+   ══════════════════════════════════════════════════════════
+
+   You're running a complete Hyprland desktop with the bread
+   ecosystem preinstalled. A few things to get you started:
+
+   • SUPER + /        show the keybind cheatsheet (any time)
+   • SUPER + ,        open BOS Settings — configure bread, the
+                      bar, launcher, Wi-Fi profiles, notes,
+                      snapshots and package updates, all in one
+                      place (no config files needed)
+   • SUPER + Space    the app launcher (breadbox)
+   • SUPER + Return   a terminal
+
+   The bar at the top (breadbar) shows workspaces, the clock,
+   system stats, and your tray. Notifications appear top-right.
+
+   Your system is snapshotted on every package change — if an
+   update breaks something, roll back from BOS Settings or pick
+   a snapshot from the GRUB menu at boot.
+
+   ──────────────────────────────────────────────────────────
+   Press q to close. This message won't show again.

iso/profiledef.sh

@@ -21,4 +21,6 @@ file_permissions=(
     ["/usr/local/bin/bos-launch-calamares"]="0:0:755"
     ["/usr/local/bin/bos-copy-kernel"]="0:0:755"
     ["/usr/local/bin/bos-session"]="0:0:755"
+    ["/usr/local/bin/bos-keybinds"]="0:0:755"
+    ["/usr/local/bin/bos-welcome"]="0:0:755"
 )

scripts/smoke-test.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# BOS post-install smoke test.
+#
+# Run this INSIDE a freshly installed BOS (as the main user) to assert the
+# install's core invariants. It is read-only and safe to run any time.
+#
+#   ./smoke-test.sh
+#
+# Exit status is non-zero if any check fails, so it can gate CI / manual QA.
+set -uo pipefail
+
+pass=0 fail=0
+ok()   { printf '  \033[32mPASS\033[0m  %s\n' "$1"; pass=$((pass+1)); }
+bad()  { printf '  \033[31mFAIL\033[0m  %s\n' "$1"; fail=$((fail+1)); }
+note() { printf '  \033[33m----\033[0m  %s\n' "$1"; }
+
+check() { if eval "$2" >/dev/null 2>&1; then ok "$1"; else bad "$1"; fi; }
+
+echo "== btrfs subvolume layout =="
+if command -v btrfs >/dev/null; then
+    # `btrfs subvolume list` needs root; try unprivileged, fall back to non-
+    # interactive sudo (no hang if creds aren't cached).
+    paths="$(btrfs subvolume list / 2>/dev/null || sudo -n btrfs subvolume list / 2>/dev/null)"
+    paths="$(awk '{print $NF}' <<<"$paths")"
+    if [ -z "$paths" ]; then
+        note "couldn't list subvolumes (need root) — skipping"
+    else
+        for sv in @ @home @snapshots @log @cache; do
+            if grep -qx "$sv" <<<"$paths"; then ok "subvolume $sv present"; else bad "subvolume $sv missing"; fi
+        done
+    fi
+else
+    note "btrfs not installed (not a btrfs root?) — skipping subvolume checks"
+fi
+
+echo "== snapshot tooling =="
+check "snapper root config exists" "[ -f /etc/snapper/configs/root ]"
+check "snap-pac hook present"      "pacman -Qq snap-pac"
+check "grub-btrfs present"         "pacman -Qq grub-btrfs"
+
+echo "== enabled system services =="
+for unit in NetworkManager.service greetd.service bluetooth.service tlp.service \
+            cups.socket avahi-daemon.service ufw.service systemd-timesyncd.service; do
+    check "$unit enabled" "systemctl is-enabled $unit"
+done
+check "graphical.target is default" "[ \"\$(systemctl get-default)\" = graphical.target ]"
+
+echo "== bread ecosystem on PATH =="
+for bin in bakery bread breadd breadbar breadbox breadbox-sync breadcrumbs breadpad breadman; do
+    check "$bin found" "command -v $bin"
+done
+
+echo "== bos-settings =="
+check "bos-settings installed" "command -v bos-settings"
+
+echo "== default dotfiles =="
+check "hyprland.lua present"  "[ -f \"\$HOME/.config/hypr/hyprland.lua\" ]"
+check "mimeapps.list present" "[ -f \"\$HOME/.config/mimeapps.list\" ]"
+check "kitty config present"  "[ -f \"\$HOME/.config/kitty/kitty.conf\" ]"
+
+echo "== bootloader (EFI) =="
+check "GRUB EFI binary present" \
+    "[ -f /boot/efi/EFI/BOS/grubx64.efi ] || [ -f /boot/efi/EFI/BOOT/BOOTX64.EFI ]"
+check "grub.cfg present" "[ -f /boot/grub/grub.cfg ]"
+
+echo
+printf 'Result: \033[32m%d passed\033[0m, \033[31m%d failed\033[0m\n' "$pass" "$fail"
+[ "$fail" -eq 0 ]