# Panama Settings Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build the approved Luminous System Settings control center and map it to `Super+I` while preserving GNOME Settings as a launcher-accessible fallback. **Architecture:** A persisted `DesktopPreferences` singleton owns user choices, `SystemSettings` owns allow-listed system reads and writes, and a normal tiled Settings window renders focused pages over those boundaries. Existing shell consumers continue through `Settings.qml`, while `ShellState` and typed IPC own window routing. **Tech Stack:** Quickshell 0.3.0, Qt 6 QML, Quickshell Io and PipeWire, Hyprland 0.56 Lua configuration, systemd, Bash integration contracts **Spec:** `docs/superpowers/specs/2026-08-17-panama-settings-design.md` ## Global Constraints - Use Tokyo Night Moon tokens and the existing Prism edge; no component-local color literals. - Apply only allow-listed Hyprland numeric settings; never execute UI-provided shell text. - Do not expose full-time desktop HDR without tested automatic rollback. - Do not continuously poll or animate while idle. - Preserve GNOME Settings as an installed, searchable fallback. - Keep unrelated pre-existing Panama changes untouched. --- ### Task 1: Persisted desktop preferences **Files:** - Create: `config/dot/quickshell/config/DesktopPreferences.qml` - Modify: `config/dot/quickshell/config/Settings.qml` - Test: `tests/quickshell/settings-preferences-contract` **Interfaces:** - Produces: writable `use24Hour`, `showSeconds`, `showWeekday`, `showCpu`, `showMemory`, `showGpu`, `dockAutohide`, `dockRevealDelayMs`, `dockHideDelayMs`, `focusDurationMinutes`, `autoHdr`, `vrrPolicy`, `directScanoutPolicy`, and `lastPage` properties plus `resetDesktopDefaults(): void`. - Consumes: `Quickshell.stateDir`, `FileView`, and `JsonAdapter`. - [x] Write a standalone Quickshell contract that changes clock, dock, and display-policy values in a disposable state directory, restarts the harness, and asserts the literal values survive. - [x] Run the contract and verify it fails because `DesktopPreferences` does not exist. - [x] Implement the JSON adapter and bind dynamic `Settings.qml` values to it. - [x] Run the persistence contract and the existing focus/dock consumers to green. ### Task 2: Allow-listed system boundary **Files:** - Create: `config/dot/quickshell/services/SystemSettings.qml` - Test: `tests/quickshell/settings-system-contract` **Interfaces:** - Consumes: `DesktopPreferences`, `NightLight`, `Notifs`, `Caffeine`, `hyprctl`, `systemctl`, and `pgrep`. - Produces: monitor identity and geometry, display-policy setters, bounded `refresh(): void`, service status, `openGnomePanel(panel: string): void`, `openApplication(id: string): void`, and an inline `lastError`. - [x] Write an IPC-backed contract that applies current policy values, refreshes the active monitor, and rejects an unsupported GNOME panel. - [x] Run it and verify the `settings-system` diagnostics target is absent. - [x] Implement fixed-command processes and strict numeric/panel allow lists. - [x] Run the contract and confirm the live compositor returns to its original values. ### Task 3: Luminous window and core pages **Files:** - Create: `config/dot/quickshell/modules/settings/SettingsWindow.qml` - Create: `config/dot/quickshell/modules/settings/SettingsShell.qml` - Create: `config/dot/quickshell/modules/settings/SettingsSidebar.qml` - Create: `config/dot/quickshell/modules/settings/SettingsCard.qml` - Create: `config/dot/quickshell/modules/settings/SettingRow.qml` - Create: `config/dot/quickshell/modules/settings/SettingsToggle.qml` - Create: `config/dot/quickshell/modules/settings/HomePage.qml` - Create: `config/dot/quickshell/modules/settings/AppearancePage.qml` - Create: `config/dot/quickshell/modules/settings/DisplaysPage.qml` - Create: `config/dot/quickshell/modules/settings/DesktopPage.qml` - Create: `config/dot/quickshell/modules/settings/qmldir` - Test: `tests/quickshell/settings-window-contract` **Interfaces:** - Consumes: `DesktopPreferences`, `SystemSettings`, `NightLight`, and `ShellState.settingsPage`. - Produces: a tiled `Panama Settings` window with Home, Appearance, Displays, and Desktop pages. - [x] Write a live contract that opens the window to each core page and verifies one `Panama Settings` toplevel remains mapped. - [x] Run it and verify the `settings` IPC target is absent. - [x] Implement the two-pane Luminous shell and reusable row/card controls. - [x] Implement real preference, Night Light, HDR policy, VRR, direct-scanout, clock, vitals, and dock controls. - [x] Run the page contract and inspect Quickshell logs for construction warnings. ### Task 4: System pages and fallback handoffs **Files:** - Create: `config/dot/quickshell/modules/settings/SoundPage.qml` - Create: `config/dot/quickshell/modules/settings/NotificationsPage.qml` - Create: `config/dot/quickshell/modules/settings/ShortcutsPage.qml` - Create: `config/dot/quickshell/modules/settings/ServicesPage.qml` - Create: `config/dot/quickshell/modules/settings/AboutPage.qml` - Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml` - Test: `tests/quickshell/settings-pages-contract` **Interfaces:** - Consumes: existing PipeWire controls, `Notifs`, `FocusSession`, service status from Task 2, and fixed GNOME panel handoffs. - Produces: Sound, Notifications & Focus, Shortcuts, Startup & Services, and About destinations. - [x] Extend the page contract with search routing, live DND/focus changes, audio construction, service refresh, and GNOME fallback command validation. - [x] Run it and verify the new page names fail before implementation. - [x] Build the five pages using the same row/card vocabulary and no inactive fake controls. - [x] Run contracts and verify absent optional services render as unavailable. ### Task 5: Shell, keybinding, launcher, and compositor integration **Files:** - Modify: `config/dot/quickshell/services/ShellState.qml` - Modify: `config/dot/quickshell/shell.qml` - Modify: `config/dot/hypr/keybinds.lua` - Modify: `config/dot/hypr/rules.lua` - Create: `config/local/share/applications/panama-settings.desktop` - Modify: `setup/scripts/link-dotfiles` - Modify: `README.md` - Modify: `config/dot/hypr/README.md` **Interfaces:** - Produces: `ShellState.settingsOpen`, `settingsPage`, typed `settings` and `settings-system` IPC targets, `Super+I`, and a searchable desktop entry. - [x] Extend the live contract to open, close, toggle, and route directly to a named page. - [x] Wire the Settings window and IPC handlers into the shell. - [x] Replace the GNOME Settings `Super+I` command with Panama IPC while retaining the GNOME desktop entry. - [x] Let the titled window participate in the active Hyprland tiling layout. - [x] Link the Panama desktop entry into `~/.local/share/applications` and refresh the launcher cache. ### Task 6: Full-system verification - [x] Run every Quickshell contract, `Hyprland --verify-config`, and desktop-file validation. - [x] Reload Hyprland, restart Quickshell, and inspect fresh logs for errors or warnings. - [x] Exercise Home, Displays, Desktop, Sound, Notifications, Services, shortcut search, and a GNOME handoff. - [x] Capture Home, Displays, Desktop, and Services pages for visual review. - [x] Inspect the exact Panama diff and confirm unrelated pre-existing changes were preserved.