---
name: nosignal
description: >-
  How to manage a NoSignal system for its user. Load this whenever you are helping
  the user configure, customize, fix, update, or troubleshoot their NoSignal machine
  (Arch Linux + Hyprland + Caelestia/Quickshell shell + SDDM). Explains the config
  override layer and exactly what is safe to edit, how to change keybinds / monitors
  / wallpaper / theme, how system updates and snapshots work, how to install
  software, and how to recover the desktop if the shell fails. Read this before
  changing any desktop or system config on a NoSignal box.
---

# NoSignal — system management skill

You are managing a **NoSignal** machine on behalf of its user: Arch Linux +
Hyprland + the Caelestia shell (Quickshell) + SDDM. A "NoSignal layer" of config and
tooling sits ON TOP of stock Caelestia. Your goal is to help the user safely —
**read the guardrails below before editing anything.** Full detail is in
`references/ONBOX-AI-NOTES.md`.

## Config layout — where to make changes (and what NOT to touch)

- **Edit here:** `~/.config/caelestia/`
  - `hypr-user.conf` — keybinds/rules/exec-once; sourced **last**, so it wins. The
    right place for new binds (`unbind =` works here).
  - `hypr-vars.conf` — `$variables` ($terminal, gaps, blur…); sourced before binds.
  - `shell.json` / `shell-tokens.json` — shell appearance/behaviour.
  - Deleting any of these restores stock behaviour.
- **Do NOT touch:**
  - `~/.config/hypr` is a **symlink** into the dotfiles clone — never replace it with
    a copy, never edit the clone's `hyprland.conf`. Use `hypr-user.conf`.
  - **Never create `~/.config/quickshell/caelestia`.** The shell runs from
    `/etc/xdg/quickshell/caelestia` with NoSignal patches re-applied by pacman hooks;
    a user copy shadows it and silently drops those patches.

## Common tasks

- **Keybinds:** add to `hypr-user.conf`; the `Super+K` cheatsheet is generated from
  `~/.local/share/nosignal/NoSignal-keybindings.md` (`nosignal-keybinds-gen`) — keep
  it in sync. Layout follows Omarchy defaults (Super+Return terminal, Super+W close,
  Super+Space launcher, Super+Grave overview, Super+C/V universal copy/paste, Print =
  region screenshot, Super+I Shelly store).
- **Monitors:** use `hyprmoncfg` (`Super+Ctrl+H`, TUI). It writes
  `~/.config/hypr/monitors.conf` (sourced by hypr-user.conf); keep the `source =`
  lines. `hyprmoncfgd` (user unit) applies profiles live on save.
- **Wallpaper / theme:** `caelestia wallpaper -f <file>` (or the UI). The Material
  colour scheme is generated FROM the wallpaper. The SDDM greeter does NOT
  auto-follow — run **`sudo sddm-theme-sync`** after a wallpaper change.
- **System updates:** **`nosignal-update`** = snapper snapshot → `yay -Syu` → run new
  migrations (tracked in `~/.local/state/nosignal/applied` — don't re-run by hand).
- **Installing software:** `yay` for AUR; **Shelly** (`shelly-ui`, Super+I) is the
  GUI store (repos + AUR + Flathub, preconfigured). Settings → **Additions** installs
  curated optional apps (DeckShift, Spotify, Once, Obsidian, OBS, Claude Code, Codex,
  opencode). NOTE: some Additions apps (e.g. **Once**) need the **Docker daemon** —
  if one errors with "Cannot connect to the Docker daemon", enable it:
  `sudo systemctl enable --now docker.socket` (and add the user to the `docker` group
  to avoid sudo).
- **Gaming mode:** OPT-IN. `sh ~/deckshift/deckshift.sh` then the deckshift-login
  installer; `Super+Shift+S` enters the gamescope/Steam session, `Super+Shift+R`
  returns. `[multilib]` is enabled.
- **Firewall:** `ufw`, enabled with Omarchy defaults — quiet; check `sudo ufw status`.

## Recovery / troubleshooting

- **Shell fails at login** (wallpaper but no bar): reproduce from a TTY with
  `qs -c caelestia -n` (`WAYLAND_DISPLAY=wayland-1`) to get the QML error chain;
  suspect the shell page patches first.
- **System broken after an update:** every pacman transaction makes a Btrfs/snapper
  snapshot; snapshots are **bootable** from the Limine menu. Worst case: reboot →
  pick an earlier snapshot.
- **Don't remove `fish`** — required by caelestia-meta even though bash is the login
  shell.

## Reference files (bundled)

`references/ONBOX-AI-NOTES.md` (full system briefing) and
`references/NoSignal-keybindings.md` (keybind reference). On a live install the
originals are in `~/.local/share/nosignal/`.

> Note: development and release-engineering concerns are **out of scope** for
> this skill — it is focused on managing the user's installed system, not on
> building or releasing the distribution.