Add first-run welcome + keybind cheatsheet onboarding

New users get a one-time welcome window on first boot (self-gating marker,
skipped for the live/installer user) and a keybind cheatsheet on SUPER+/.
Also bind BOS Settings to SUPER+, (it had no launcher bind). Both popups
are floated/centred via window rules. Addresses the onboarding/
discoverability gap from external review.

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

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"
 )