diff --git a/README.md b/README.md index a70fef3..930804c 100644 --- a/README.md +++ b/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 diff --git a/iso/airootfs/etc/skel/.config/hypr/hyprland.lua b/iso/airootfs/etc/skel/.config/hypr/hyprland.lua index 857975b..8485e0c 100644 --- a/iso/airootfs/etc/skel/.config/hypr/hyprland.lua +++ b/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)) diff --git a/iso/airootfs/usr/local/bin/bos-keybinds b/iso/airootfs/usr/local/bin/bos-keybinds new file mode 100644 index 0000000..4d036cb --- /dev/null +++ b/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 diff --git a/iso/airootfs/usr/local/bin/bos-welcome b/iso/airootfs/usr/local/bin/bos-welcome new file mode 100644 index 0000000..413256b --- /dev/null +++ b/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 diff --git a/iso/airootfs/usr/share/bos/keybinds.txt b/iso/airootfs/usr/share/bos/keybinds.txt new file mode 100644 index 0000000..4ecf0b7 --- /dev/null +++ b/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 + ,). diff --git a/iso/airootfs/usr/share/bos/welcome.txt b/iso/airootfs/usr/share/bos/welcome.txt new file mode 100644 index 0000000..a412f4a --- /dev/null +++ b/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. diff --git a/iso/profiledef.sh b/iso/profiledef.sh index ed30e07..ecc995e 100644 --- a/iso/profiledef.sh +++ b/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" ) diff --git a/scripts/smoke-test.sh b/scripts/smoke-test.sh new file mode 100755 index 0000000..a551253 --- /dev/null +++ b/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 ]