docs: rebuild KB in OKF v0.1 with live-verified facts

Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
2026-08-28 07:57:13 -07:00
1 parent 552d1ef8bf
commit 02883d3ed2
@@ -0,0 +1,128 @@
+---
+type: reference
+title: Noctalia Shell
+description: Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls.
+tags:
+  - noctalia
+  - quickshell
+  - wayland
+  - shell
+  - launcher
+timestamp: 2026-08-06
+---
+
+# Noctalia Shell
+
+Noctalia Shell is a sleek, minimal desktop shell for Wayland built with [Quickshell](https://github.com/outfoxxed/quickshell). It provides an app launcher, wallpaper manager, session menu, lock screen, hotkey overlay, media controls, and brightness/volume controls.
+
+**Version:** 4.7.7
+**Dependency:** noctalia-qs / qs 0.0.12
+
+---
+
+## Architecture
+
+Noctalia communicates through an IPC system accessed via the `qs` command:
+
+```bash
+qs -c noctalia-shell ipc call <module> <action> [params]
+```
+
+## Components
+
+| Component | IPC Command | Description |
+|-----------|-------------|-------------|
+| **Shell** | `qs -c noctalia-shell` | Main shell process |
+| **Launcher** | `ipc call launcher toggle` | Application launcher |
+| **Lock Screen** | `ipc call lockScreen lock` | Screen locker |
+| **Session Menu** | `ipc call sessionMenu toggle` | Power/logout menu |
+| **Hotkey Overlay** | `ipc call overlay toggle` | Visual keybind reference |
+| **Volume** | `ipc call volume increase/decrease/muteOutput` | Audio controls |
+| **Media** | `ipc call media playPause/next/previous` | Media playback |
+| **Brightness** | `ipc call brightness increase/decrease` | Display brightness |
+| **Wallpaper** | Layer namespace `noctalia-wallpaper*` | Desktop wallpaper |
+
+---
+
+## Niri Integration
+
+Noctalia is deeply integrated with the Niri compositor configuration:
+
+### Autostart
+
+**File:** `~/.config/niri/cfg/autostart.kdl`
+
+```kdl
+spawn-sh-at-startup "qs -c noctalia-shell"
+```
+
+### Keybindings
+
+**File:** `~/.config/niri/cfg/keybinds.kdl`
+
+| Keybind | Action | IPC Command |
+|---------|--------|-------------|
+| `Mod+Return` | Terminal | `spawn "ghostty"` |
+| `Mod+CTRL+Return` | App Launcher | `noctalia-shell ipc call launcher toggle` |
+| `Mod+B` | Browser | `spawn "firefox"` |
+| `Mod+ALT+L` | Lock Screen | `noctalia-shell ipc call lockScreen lock` |
+| `Mod+Shift+Q` | Session Menu | `noctalia-shell ipc call sessionMenu toggle` |
+| `Mod+Shift+Escape` | Hotkey Overlay | `show-hotkey-overlay` |
+| `Mod+E` | File Manager | `spawn "nautilus"` |
+
+### Media and Brightness
+
+| Key | Action | IPC Command |
+|-----|--------|-------------|
+| `XF86AudioRaiseVolume` | Volume Up | `volume increase` |
+| `XF86AudioLowerVolume` | Volume Down | `volume decrease` |
+| `XF86AudioMute` | Mute | `volume muteOutput` |
+| `XF86AudioMicMute` | Mic Mute | `volume muteInput` |
+| `XF86AudioPlay` | Play/Pause | `media playPause` |
+| `XF86AudioNext` | Next Track | `media next` |
+| `XF86AudioPrev` | Previous | `media previous` |
+| `XF86MonBrightnessUp` | Brightness Up | `brightness increase` |
+| `XF86MonBrightnessDown` | Brightness Down | `brightness decrease` |
+
+### Wallpaper
+
+The wallpaper layer is placed in the backdrop:
+
+```kdl
+// In ~/.config/niri/cfg/rules.kdl
+layer-rule {
+    match namespace="^noctalia-wallpaper*"
+    place-within-backdrop true
+}
+```
+
+The background color is set to transparent to allow the wallpaper to show:
+
+```kdl
+// In ~/.config/niri/cfg/layout.kdl
+layout {
+    background-color "transparent"
+}
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `noctalia-qs` / `qs` | Quickshell runtime |
+| `imagemagick` | Image processing |
+| `brightnessctl` | Brightness control |
+| `ffmpeg` | Media processing |
+| `qt6-multimedia` | Qt multimedia |
+| `python` | Python runtime |
+| `wlr-randr` | Display information |
+
+---
+
+## See Also
+
+- [niri](niri/index.md) — Compositor configuration
+- [[displays|displays]] — Display layout
+- [[cachyos|cachyos]] — Operating system documentation