Panama/docs/superpowers/plans/2026-08-18-roadmap-completion.md

# Panama Roadmap Completion 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:** Close every audited correctness gap and finish the approved Phase 3–5 Panama roadmap.

**Architecture:** Preserve Settings, `DesktopPreferences`, and `Theme.qml` as the existing ownership spine. Add narrowly scoped event observers, adapters, and generated artifacts around those boundaries; contextual shell surfaces only route into Settings. Each task is independently committed and contract-tested before final integration.

**Tech Stack:** Quickshell/QML, JavaScript, Bash, Python 3, Hyprland Lua, systemd user units, `jq`.

**Spec:** `docs/superpowers/specs/2026-08-18-roadmap-completion-design.md`

## Global Constraints

- Preserve the current Prism/Tokyo Night design language and existing component library.
- Do not introduce continuously repainting effects or polling loops.
- Do not expose or modify `config/bash/env`.
- Write a failing contract before each production change and record the red/green commands.
- Keep interactive QML harnesses and Quickshell restarts for the final integration gate.
- Generated and user-owned files must be written atomically.
- No production configuration is activated until the reviewed branch is merged.

---

### Task 1: Close Phase 1 and Phase 2 safety gaps

**Files:**
- Modify: `config/dot/quickshell/services/ColorScheme.qml`
- Modify: `config/dot/quickshell/modules/settings/README.md`
- Modify: `config/dot/hypr/looks.lua`
- Modify: `config/dot/quickshell/services/Displays.qml`
- Modify: `config/dot/quickshell/modules/settings/DisplaysPage.qml`
- Modify: `config/dot/quickshell/scripts/panama-lock`
- Modify: `config/dot/quickshell/services/Wallpaper.qml`
- Modify: `config/dot/quickshell/modules/settings/WallpaperControls.qml`
- Test: `tests/quickshell/settings-ownership-contract.sh`
- Test: `tests/quickshell/display-transaction-contract.sh`
- Test: `tests/quickshell/lock-screen-helper-contract.sh`
- Test: `tests/quickshell/wallpaper-service-contract.sh`
- Test: `tests/quickshell/wallpaper-settings-contract.sh`

**Interfaces:**
- Produces: `Displays.primaryFirstMonitors`, event-driven topology refresh, and a lock helper that never emits an unreadable image.
- Consumes: current `Theme.accent`, `Theme.accentSecondary`, display transaction rollback, and wallpaper preference schema.

- [ ] Add failing ownership assertions that active borders derive from `Theme.accent` and `Theme.accentSecondary`, while inactive borders derive only from scheme roles; verify the current contract fails for the stale prohibition.
- [ ] Update the ownership implementation comments and documentation, then run `bash tests/quickshell/settings-ownership-contract.sh` and verify PASS.
- [ ] Add a failing display fixture that changes the harness screen model without calling the display service’s public `refresh()` and expects topology reconciliation plus rollback of a pending transaction.
- [ ] Add an event-driven screen-model observer and primary-first derived monitor list; run `bash tests/quickshell/display-transaction-contract.sh` and `bash tests/quickshell/display-layout-contract.sh`.
- [ ] Add failing lock fixtures for missing global and per-monitor wallpapers, requiring readable shipped-image fallback and screenshot fallback when no image exists.
- [ ] Tighten `panama-lock` path validation and bounded warnings; run `bash tests/quickshell/lock-screen-helper-contract.sh`.
- [ ] Add failing wallpaper contracts for primary-first output order, selection preservation, and a HOME path containing a single quote.
- [ ] Replace inline `bash -lc` path interpolation with an argument-safe helper and update controls to preserve selection; run both wallpaper contracts.
- [ ] Run the Task 1 contract set and commit with message `Close desktop safety gaps`.

### Task 2: Complete contextual configuration and reliable overview capture

**Files:**
- Modify: `config/dot/quickshell/modules/dock/Dock.qml`
- Modify: relevant dock context-menu component if already split
- Modify: `config/dot/quickshell/modules/notifications/NotificationCard.qml`
- Modify: `config/dot/quickshell/modules/osd/Osd.qml`
- Modify: `config/dot/quickshell/modules/overview/WindowThumbnail.qml`
- Modify: `config/dot/quickshell/services/ShellState.qml`
- Test: `tests/quickshell/settings-jump-contract.sh`
- Create or modify: `tests/quickshell/overview-thumbnail-contract.sh`

**Interfaces:**
- Produces: one route per configurable surface into the existing owning Settings page.
- Consumes: `ShellState.openSettings(page)` and the existing app-icon thumbnail fallback.

- [ ] Extend the settings-jump contract so it fails until dock, notifications, and OSD each expose a contextual Settings route without replacing their primary action.
- [ ] Add the three restrained contextual actions using existing menu/button styles and Settings routes.
- [ ] Add a failing static/isolated contract proving capture does not start before recording readiness, is bounded, and retains the icon fallback.
- [ ] Gate capture on recording readiness or the appropriate Quickshell frame-ready signal, remove warning-producing blind retries, and keep capture event-driven.
- [ ] Run both contracts and commit with message `Complete contextual desktop controls`.

### Task 3: Complete advanced accents and named themes

**Files:**
- Modify: `config/dot/quickshell/config/PreferenceSchema.qml`
- Modify: `config/dot/quickshell/config/Theme.qml`
- Create: `config/dot/quickshell/services/ThemeProfiles.qml`
- Modify: `config/dot/quickshell/modules/settings/AccentPicker.qml`
- Create: `config/dot/quickshell/modules/settings/AccentEditor.qml`
- Create: `config/dot/quickshell/modules/settings/ThemeProfilePicker.qml`
- Modify: `config/dot/quickshell/modules/settings/AppearancePage.qml`
- Modify: `config/dot/quickshell/services/ColorScheme.qml`
- Modify: `config/dot/quickshell/services/SettingsSearch.qml`
- Test: create `tests/quickshell/theme-profiles-contract.sh`
- Test: create `tests/quickshell/accent-controls-contract.sh`
- Test: modify `tests/quickshell/control-center-contract.sh`

**Interfaces:**
- Produces: profile records `{id,name,scheme,accent,secondary,shipped}` and reactive `Theme` colour roles.
- Consumes: `DesktopPreferences`, `SystemSettings.commitPreference`, `hyprpicker`, and current Prism Settings components.

- [ ] Write failing pure-model fixtures for three shipped profiles, custom profile creation, bounded unique names, shipped-profile immutability, and HSV/hex conversion.
- [ ] Implement `ThemeProfiles` with Moon, Moon Rose, and Day plus saved custom profiles, then verify model tests.
- [ ] Write failing UI contracts for labelled HSV controls, curated swatches, keyboard focus, screen picking, profile save/switch/delete, and search routing.
- [ ] Build the profile picker and advanced editor from existing `SettingRow`, `ValueSlider`, `SettingsButton`, and focus tokens; do not add ambient animation.
- [ ] Update `Theme.qml` and `ColorScheme` so custom pairs reactively reach shell roles and Hyprland borders.
- [ ] Extend the Control Center contract to cover power profiles, night light, and colour scheme controls added after its original contract.
- [ ] Run theme, accent, ownership, settings-search, and Control Center contracts; commit with message `Complete the Panama theme system`.

### Task 4: Propagate the accent to external applications

**Files:**
- Modify: `config/dot/quickshell/scripts/panama-theme-apps`
- Modify: `config/dot/quickshell/services/ColorScheme.qml`
- Modify: tracked kitty/tmux/Vicinae/Wofi/Neovim include points as required
- Create: generated-file templates or helpers under the owning application directories
- Test: create `tests/quickshell/theme-apps-accent-contract.sh`
- Test: modify `tests/quickshell/gtk-theme-contract.sh` if its invocation contract changes

**Interfaces:**
- Produces: `panama-theme-apps dark|light [#RRGGBB #RRGGBB]` with per-adapter JSON status.
- Consumes: the selected profile’s validated primary and secondary accents.

- [ ] Write a failing isolated fixture invoking the helper with dark/light and custom pairs, asserting atomic generated overrides for kitty, tmux, btop, Vicinae/Wofi, hyprlock, and Neovim plus backward-compatible two-state invocation.
- [ ] Implement validated optional accent arguments and independent adapters; never rewrite user-owned base files wholesale.
- [ ] Update each application’s tracked config to include its generated accent override after the base Tokyo Night theme.
- [ ] Pass the selected pair from `ColorScheme` and expose bounded adapter failures through its existing error state.
- [ ] Run the isolated helper contract, GTK contract, Bash syntax, and a fixture-only idempotence check; commit with message `Propagate accents across desktop applications`.

### Task 5: Finish onboarding, recovery automation, and generated docs

**Files:**
- Modify: `config/dot/quickshell/config/PreferenceSchema.qml`
- Create: `config/dot/quickshell/modules/settings/WelcomePage.qml`
- Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml`
- Modify: `config/dot/quickshell/modules/settings/SettingsSidebar.qml`
- Modify: `config/dot/quickshell/services/SettingsSearch.qml`
- Modify: `config/dot/quickshell/services/SystemSettings.qml`
- Modify: display/theme/reset/restore call sites for pre-risk snapshots
- Modify: `setup/scripts/link-dotfiles`
- Create: user systemd snapshot service/timer files under the existing systemd config tree
- Create: `config/dot/quickshell/scripts/panama-generate-docs`
- Create: `docs/SETTINGS.md`
- Create: `docs/SHORTCUTS.md`
- Test: create `tests/quickshell/first-run-contract.sh`
- Test: modify `tests/quickshell/settings-backup-live-contract.sh`
- Test: create `tests/quickshell/generated-docs-contract.sh`
- Test: modify `tests/quickshell/keybind-rebind-contract.sh`

**Interfaces:**
- Produces: fresh-install marker lifecycle, `snapshot --cause <cause>` retention, and deterministic generated Markdown.
- Consumes: existing Settings navigation, backup/restore helper, preference schema, and shipped keybind metadata.

- [ ] Write failing first-run fixtures proving only fresh installs get a marker, completion removes it atomically, existing settings are not interrupted, and Welcome remains searchable.
- [ ] Implement the Welcome page and marker lifecycle using existing card/row components.
- [ ] Add failing backup fixtures for daily retention and pre-risk snapshots before display layout, named theme, reset-all, and restore operations.
- [ ] Extend the backup helper/service with labelled atomic snapshots, fourteen-day retention, and a systemd user timer; wire the four risky call sites.
- [ ] Strengthen keybind contracts to explicitly cover both rebind and reset collisions.
- [ ] Write a failing drift contract for generated settings and shortcut documentation.
- [ ] Implement the deterministic generator, generate both Markdown files, and verify a second run produces no diff.
- [ ] Run first-run, backup, keybind, generated-docs, schema, and search contracts; commit with message `Finish onboarding and desktop recovery`.

### Task 6: Integrate, review, activate, and verify live readiness

**Files:**
- Modify only files required by review findings.
- Update roadmap/status documentation to mark exact delivered scope.

**Interfaces:**
- Consumes: all preceding task commits.
- Produces: reviewed `main`, pushed origin, one activated Quickshell session, and an evidence ledger.

- [ ] Run `git diff --check`, executable Bash syntax, Lua syntax, generated-doc drift, every non-interactive Quickshell contract, and Hyprland configuration validation.
- [ ] Dispatch a whole-branch code review against this plan and fix every Critical/Important finding with one reviewed fix wave.
- [ ] Merge the reviewed branch into `main` without rewriting shared history and push `origin/main`.
- [ ] Run the repository’s user-level setup/link step needed for new systemd units and autostarts; do not print environment secrets.
- [ ] Resolve live health where locally actionable: enable RustDesk and Nextcloud user autostart, install/link calendar integration if its declared dependency is already available, and leave hardware-only DDC as a documented warning.
- [ ] Restart Quickshell once, perform the interactive visual/runtime gate, inspect logs for QML errors and screencopy warnings, and run `panama-doctor --json`.
- [ ] Record exact passed commands, remaining environment-only observations, and final commit IDs.