NoSignal-OS/os updates/ONBOX-AI-NOTES.md

NoSignal — notes for an AI agent working on this machine

You are on NoSignal: Arch Linux + Hyprland + the Caelestia shell (Quickshell)

• SDDM (themed greeter). A "NoSignal layer" of config and tooling sits ON TOP of stock Caelestia. Read this before changing desktop/system config — your job is to help the user manage their machine safely.

Config layout — what is safe to edit

• ~/.config/caelestia/ — the NoSignal override layer (edit here):
  • hypr-user.conf — user binds/rules/exec-once; sourced LAST, so it wins. This is the right place for new keybinds. unbind = works here.
  • hypr-vars.conf — $variables ($terminal, $kb*, gaps, blur…); sourced BEFORE keybinds.conf consumes them.
  • shell.json, shell-tokens.json — Caelestia shell appearance/behaviour.
  • Deleting any of these files restores stock Caelestia behaviour.
• ~/.config/hypr is a SYMLINK into ~/.local/share/caelestia (the dotfiles clone). Several other ~/.config entries (foot, fish, fastfetch, uwsm) are symlinks into it too. Never replace these symlinks with copies and never edit the clone's hyprland.conf directly — use hypr-user.conf.
• ~/.config/hypr/scripts/wsaction.fish and configs.fish are bash ports kept under their original .fish names (the stock config calls those paths). Keep the names and the bash shebang.

Updates

• ~/.local/share/nosignal/ — the on-system layer: component sources, the keybindings doc, and nosignal-update/ (the update command + its migrations).
• nosignal-update = the system update command: snapper snapshot → yay -Syu → run any NEW migrations. Applied migrations are tracked in ~/.local/state/nosignal/applied — do not re-run or edit by hand.

Keybindings

• Super+K (aliases Super+/, Super+F1) = searchable fuzzel cheatsheet.
• Source of truth: ~/.local/share/nosignal/NoSignal-keybindings.md — the cheatsheet is GENERATED from it (nosignal-keybinds-gen). If you add a bind in hypr-user.conf, document it in that file too.
• Layout follows Omarchy defaults: Super+Return terminal (kitty, bash), Super+W close, Super+Space launcher, Super+Tab next workspace, Super+Grave = workspace overview, Super+I Shelly store, Super+Ctrl+H monitor editor, Super+Shift+number move-to-workspace (bound by KEYCODE — GB layout).
• Super+C / Super+V = universal copy/paste (class-aware sendshortcut; clipboard HISTORY is Super+Ctrl+V). Print = region screenshot → clipboard + ~/Pictures/Screenshots (Shift+Print full). Super+D = dashboard/calendar (communication workspace → Super+Shift+D). Super+M = CLIAmp, the default music player (floating TUI; audio files open in it via ~/.config/mimeapps.list). The shell's music/MPRIS panel is Super+Shift+M.

Shell / desktop architecture gotchas

• The Caelestia shell runs from /etc/xdg/quickshell/caelestia. NoSignal patches THREE things there, each re-applied by its own pacman hook after every caelestia-shell upgrade: the Settings → System → Updates page (PageCompRegistry.qml + pages/UpdatesPage.qml), the Settings → Additions page (same registry + pages/AdditionsPage.qml + Plugins→Additions relabel in PageRegistry.qml; backend = nosignal-additions + additions.json in the layer tree), and the Wi-Fi wrong-password recovery in utils/NetworkConnection.qml. Do NOT create ~/.config/quickshell/caelestia — a user copy shadows /etc/xdg and silently drops the patches (and future ones). If the shell ever fails at login (background but no bar): reproduce with qs -c caelestia -n from a TTY (WAYLAND_DISPLAY=wayland-1) to get the QML error chain; suspect the page patches first.
• The workspace overview is a separate Quickshell instance (~/.config/quickshell/overview, qs -c overview -d, IPC-toggled by Super+Grave). It is independent of the main shell.
• The update-status timer (nosignal-update-check.timer, user), hyprmoncfgd (monitor hotplug profiles, user) and hyprmoncfgd-rescan.path (watches ~/.config/hyprmoncfg/profiles/ and bounces the daemon so plain profile saves apply live) are enabled systemd USER units. Status: systemctl --user status <unit>.

Monitors

• Use hyprmoncfg (Super+Ctrl+H, TUI) — it writes ~/.config/hypr/monitors.conf (+ workspaces.conf), which hypr-user.conf sources. Keep those source = lines; hyprmoncfg refuses to write otherwise.
• Both the TUI bind and the hyprmoncfgd daemon run with --hypr-config ~/.config/caelestia/hypr-user.conf --monitors-conf ~/.config/hypr/monitors.conf (hyprmoncfg doesn't follow nested source = includes). Keep the flags; the daemon's drop-in lives at ~/.config/systemd/user/hyprmoncfgd.service.d/override.conf.

Login / display manager / gaming

• SDDM is the display manager. Config drop-ins in /etc/sddm.conf.d/: 10-nosignal.conf (X11 greeter, uwsm session notes) + 20-sddm-theme.conf (themed greeter). The desktop session MUST stay hyprland-uwsm.desktop (uwsm-managed) — plain hyprland.desktop loses caelestia's session env.
• The greeter theme (/usr/share/sddm/themes/caelestia) mirrors the desktop scheme. After changing wallpaper, run sudo sddm-theme-sync to update the login screen (it does not auto-follow).
• Gaming Mode is OPT-IN: run sh ~/deckshift/deckshift.sh, then sh ~/.local/share/nosignal/deckshift-login/install-deckshift-login.sh (re-run the fix after any deckshift.sh re-run). Then Super+Shift+S enters the full gamescope/Steam session; Super+Shift+R (inside it) returns. Cold boots always show the password greeter (one-shot autologin). [multilib] is enabled and omarchy-pkg-add & friends are shims in ~/.local/bin.

Packages / system

• yay for AUR; Shelly (shelly-ui, Super+I) is the GUI store (repos + AUR + Flathub). Flathub remote is preconfigured. Settings → Additions installs curated optional software (DeckShift, Spotify, Once, Obsidian, OBS, Claude Code, Codex, opencode) from official sources only — extend via additions.json in the layer tree, no code changes.
• The firewall is ufw, enabled with Omarchy-style defaults — it is easy to miss because nothing advertises it: sudo ufw status.
• The fish package is REQUIRED by caelestia-meta — do not remove it, even though bash is the login/terminal shell.
• Btrfs + snapper: every pacman transaction snapshots (snap-pac); snapshots are BOOTABLE from the Limine menu (limine-snapper-sync, UKI at /boot/EFI/Linux/nosignal_linux.efi). Worst case: reboot → pick a snapshot.
• [omarchy] repo in pacman.conf provides prebuilt limine-snapper tools.
• omarchy-send is installed (LAN file transfer; receive dir ~/Omarchy-Send, TUI in launcher, CLI: omarchy-send -to <alias> <files>). Its config contains a private key — never copy/share ~/.config/omarchy-send/.

Theme

• Wallpapers: ~/Pictures/Wallpapers/nosignal/ (the OS art set; default foam-sea.png). The colour scheme is Caelestia's dynamic Material scheme, generated FROM the current wallpaper — change wallpaper via the Caelestia UI or caelestia wallpaper -f <file> and the palette follows. The SDDM greeter does NOT auto-follow: run sudo sddm-theme-sync after.