# Panama Settings Completion Codex 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:** Complete Codex's portion of Panama Settings with default-application and autostart management, shared page scaffolds, and real controls for every remaining hardcoded shell behavior value. **Architecture:** `DefaultApps.qml` is the typed system boundary for freedesktop default handlers and user autostart entries; `ApplicationsPage.qml` binds reactively to `DesktopEntries.applications.values` and never snapshots the asynchronous model. Existing pages adopt `SettingsPage`; schema-bound values use `ChoiceRow`, `SliderRow`, and `ToggleRow`, while specialized controls and genuinely read-only facts remain specialized or use `TextRow`. **Tech Stack:** Quickshell 0.3 QML, QtQuick, `xdg-settings`, `xdg-mime`, freedesktop `.desktop` files, Bash/Python contract tests, Hyprland. **Spec:** `docs/superpowers/specs/2026-08-17-panama-cohesion-design.md` **Status:** Implemented and independently reviewed on 2026-08-18. The combined verification gate is recorded in the integrating commit history. ## Global Constraints - Claude owns and must be the only editor of `PreferenceSchema.qml`, `SettingsSidebar.qml`, `SettingsShell.qml`, `qmldir`, `ShellState.qml`, `SystemSettings.qml`, `AppearancePage.qml`, `DesktopPage.qml`, `ShortcutsPage.qml`, and `config/dot/hypr/*`. - Never use `hyprctl keyword`; every `hl.bind` requires a description. - Use `DesktopEntries.applications.values` in reactive bindings. Do not call `byId()` or `heuristicLookup()` in a one-time initialization path. - Use `SettingRow.activatable` for whole-row clicks. Nested Repeaters address outer models through explicit ids, never `parent.modelData`. - Only these verified GNOME panels may be opened: applications, background, bluetooth, color, display, keyboard, mouse, multitasking, network, notifications, online-accounts, power, printers, privacy, search, sharing, sound, system, universal-access, wacom, wellbeing, wifi, wwan. - No mock phase, new visual direction, color literals, or idle animation. Preserve page copy and behavior unless a dead read-only row is replaced by a real control. - Automated tests isolate XDG config/state, do not change live defaults or autostart entries, do not launch applications, and do not invoke Home actions. --- ### Task 1: Applications, default handlers, and user autostart **Files:** - Create: `config/dot/quickshell/services/DefaultApps.qml` - Create: `config/dot/quickshell/modules/settings/ApplicationsPage.qml` - Create only if needed for a safe parser/writer boundary: `config/dot/quickshell/scripts/panama-default-apps` - Create: `tests/quickshell/default-apps-contract` - Create: `tests/quickshell/applications-settings-contract` **Interfaces:** - Consumes: `DesktopEntries.applications.values`, `SettingsPage`, `SettingsCard`, `SettingRow.activatable`, `ActionRow`, `TextRow`, and Claude-owned routing for page id `applications`. - Produces: a singleton `DefaultApps` with reactive `handlers`, `autostartEntries`, `luaAutostartEntries`, `busy`, `lastError`, `refresh()`, `setDefault(role, desktopId)`, and `setAutostart(desktopId, enabled)`. - [x] **Step 1: Write failing helper/service and page contracts** Cover seven roles: browser (`xdg-settings default-web-browser`), mail (`x-scheme-handler/mailto`), files (`inode/directory`), terminal (`x-scheme-handler/terminal`), music (`audio/mpeg`), images (`image/png`), and video (`video/mp4`). Use temporary XDG directories and fake `xdg-settings`/`xdg-mime` binaries; assert setters pass separate arguments and reject unknown roles or desktop ids. Fixture user autostart entries must expose id/name/enabled and toggle with standard `Hidden=` semantics; `hl.exec_cmd` entries parsed from `config/dot/hypr/autostart.lua` are read-only and identify their source. The page contract must require `DesktopEntries.applications.values`, page id/object name, all seven role labels, user and compositor autostart sections, `SettingRow.activatable`, and must reject `Component.onCompleted` snapshots plus `byId()`/`heuristicLookup()`. - [x] **Step 2: Run focused contracts to verify RED** ```bash tests/quickshell/default-apps-contract tests/quickshell/applications-settings-contract ``` Expected: fail because the service/page and behavior do not exist. - [x] **Step 3: Implement the minimal typed boundary and page** All process commands use argument arrays. Validate roles against a fixed map and desktop ids against the reactive applications model or a strict freedesktop id pattern plus discovered entries. The page filters role choices from category/generic-name data, sorts by display name, keeps the current handler visible even when category metadata is sparse, and shows calm inline errors. Toggling applies only to files under `$XDG_CONFIG_HOME/autostart`; Lua entries remain read-only with explanatory copy. - [x] **Step 4: Verify and commit** ```bash tests/quickshell/default-apps-contract tests/quickshell/applications-settings-contract tests/quickshell/settings-pages-contract ``` Commit subject: `Add application and autostart settings`. --- ### Task 2: Remaining page scaffolds and hardcoded behavior controls **Files:** - Modify: `config/dot/quickshell/config/Settings.qml` - Modify: `config/dot/quickshell/modules/settings/HomePage.qml` - Modify: `config/dot/quickshell/modules/settings/DisplaysPage.qml` - Modify: `config/dot/quickshell/modules/settings/ConnectivityPage.qml` - Modify: `config/dot/quickshell/modules/settings/SoundPage.qml` - Modify: `config/dot/quickshell/modules/settings/NotificationsPage.qml` - Modify: `config/dot/quickshell/modules/settings/ScreenIntelligencePage.qml` - Modify: `config/dot/quickshell/modules/settings/ServicesPage.qml` - Modify: `config/dot/quickshell/modules/settings/AboutPage.qml` - Modify: `tests/quickshell/settings-pages-contract` - Create: `tests/quickshell/settings-hardcoded-values-contract` **Interfaces:** - Consumes: Claude-owned schema keys `temperatureUnit`, `weatherRefreshMinutes`, `vitalsIntervalMs`, `notificationTimeoutMs`, `notificationTimeoutCriticalMs`, `notificationHistoryLimit`, `maxVisibleToasts`, `screenshotDir`, `recordingDir`, and `recorderArgs`; shared Settings rows; existing services and system handoffs. - Produces: the same public `Settings.qml` properties, now each reading `DesktopPreferences.get("key")`, and controls routed to weather/vitals, notifications, and capture pages. - [x] **Step 1: Write failing contracts** Require all ten `Settings.qml` properties to use `DesktopPreferences.get()` exactly. Require every listed page root to be `SettingsPage` and reject its copied root `Flickable` scaffold. Require weather/vitals controls on `HomePage`, notification controls on `NotificationsPage`, and capture directory/encoder controls on `ScreenIntelligencePage`; every schema-bound control uses a shared row and writes only through `SystemSettings.commitPreference` via that row. - [x] **Step 2: Run contracts to verify RED** ```bash tests/quickshell/settings-hardcoded-values-contract tests/quickshell/settings-pages-contract ``` Expected: fail on hardcoded properties and copied page scaffolds. - [x] **Step 3: Implement controls and migrate scaffolds** Use `ChoiceRow` for `temperatureUnit`, `screenshotDir`, `recordingDir`, and `recorderArgs`; use `SliderRow` for numeric refresh, timeout, history, and toast limits. Give `notificationTimeoutCriticalMs` `zeroLabel: "Never"`. Preserve all specialized buttons, service status rows, display diagnostics, permission/privacy explanations, and GNOME handoff actions. Convert genuinely read-only rows to `TextRow`; delete only rows superseded by working controls. - [x] **Step 4: Run focused and full suite, then commit** ```bash tests/quickshell/settings-hardcoded-values-contract tests/quickshell/settings-pages-contract tests/quickshell/settings-preferences-contract tests/quickshell/settings-search-contract ``` Then run every `tests/quickshell/*`, every `tests/hypr/*`, and all three `tests/quickshell/*_test.py` files sequentially. Commit subject: `Complete Panama settings controls`.