From f8e7512e01291b812fe4bab505848a22350ae3ef Mon Sep 17 00:00:00 2001 From: Gabriel Brown Date: Tue, 18 Aug 2026 11:36:06 -0400 Subject: [PATCH] Document Panama health and recovery --- config/dot/hypr/DESKTOP-PARITY.md | 25 ++++++++++++++++++ .../dot/quickshell/modules/settings/README.md | 25 ++++++++++++++++++ .../2026-08-18-panama-health-recovery.md | 26 +++++++++++++++++-- 3 files changed, 74 insertions(+), 2 deletions(-) diff --git a/config/dot/hypr/DESKTOP-PARITY.md b/config/dot/hypr/DESKTOP-PARITY.md index 6d22840..f80250d 100644 --- a/config/dot/hypr/DESKTOP-PARITY.md +++ b/config/dot/hypr/DESKTOP-PARITY.md @@ -37,6 +37,31 @@ Last live audit: 2026-08-17, Fedora 44, Hyprland 0.56.2, Quickshell 0.3.0. | Autostart apps | Nextcloud, Bitwarden, and RustDesk system service/tray | Live | | Printer administration | CUPS with the `system-config-printer` graphical interface | Live | | System settings | The Settings app for display policy, appearance, desktop, sound, focus, shortcuts, and services; labelled GNOME hardware/account handoffs | Live | +| System health and recovery | Settings → System Health, `Panama: Check System Health` in Vicinae, a degraded-only bar indicator, redacted reports, and bounded Panama-owned repairs | Live | + +## System health and recovery + +Panama stays silent while the desktop is healthy. A compact bar indicator +appears only for actionable warnings or errors and opens the same **System +Health** page available from Settings and the Vicinae command **Panama: Check +System Health**. The terminal summary is available with: + +```bash +~/.config/quickshell/scripts/panama-doctor --summary +``` + +The doctor reports authored, redacted observations about Panama-owned services, +tools, links, and configured integrations. It does not read secrets, clipboard +or notification contents, calendar events, SSIDs, or device addresses. Repairs +are a small allow-list: Panama user services, Panama-owned links and launcher +commands, duplicate Panama Caffeine inhibitors, and a confirmed shell restart. +They never install packages, invoke `sudo`, delete user data, or rewrite +arbitrary configuration. + +Generic Fedora configuration remains with the system tools that own it. The +final System Health card hands network settings, users, sharing, colour +profiles, and digital wellbeing to their exact GNOME Settings panels rather +than presenting inert Hyprland controls. ## GNOME extension migration diff --git a/config/dot/quickshell/modules/settings/README.md b/config/dot/quickshell/modules/settings/README.md index 31dc5ea..a2db36c 100644 --- a/config/dot/quickshell/modules/settings/README.md +++ b/config/dot/quickshell/modules/settings/README.md @@ -4,6 +4,31 @@ The control centre for everything Panama owns. Anything the system owns — hardware, accounts, printers — is delegated to GNOME Settings and labelled as such rather than half-reimplemented. +## System Health + +The stable internal `services` route renders **System Health**. It is reachable +from the Settings sidebar and its live 54px footer, the degraded-only bar +indicator, and Vicinae's **Panama: Check System Health** command. Healthy scans +reserve no bar space and produce no notification. + +`services/Health.qml` owns the last accepted redacted snapshot and invokes only +`scripts/panama-doctor`. For a concise terminal view, run: + +```bash +~/.config/quickshell/scripts/panama-doctor --summary +``` + +The helper diagnoses Panama-owned desktop services, dependencies, links, and +configured integrations. It does not read secret values, clipboard or +notification contents, calendar events, SSIDs, addresses, or arbitrary command +output. Its repair interface is an authored allow-list: it never installs a +package, runs `sudo`, deletes user data, or repairs a service Panama does not +own. A repair remains degraded until a fresh scan observes recovery. + +The final card is the ownership boundary. Network configuration and the exact +Users, Sharing, Colour profiles, and Digital wellbeing handoffs open GNOME +Settings because Fedora's system services own those areas. + ## Adding a setting One schema entry. That is the whole job. diff --git a/docs/superpowers/plans/2026-08-18-panama-health-recovery.md b/docs/superpowers/plans/2026-08-18-panama-health-recovery.md index a0ff53b..82dbe9b 100644 --- a/docs/superpowers/plans/2026-08-18-panama-health-recovery.md +++ b/docs/superpowers/plans/2026-08-18-panama-health-recovery.md @@ -498,6 +498,19 @@ git commit -m "Add bounded Panama recovery actions" ### Task 7: Full verification, live read-only audit, and documentation +**Integration note:** `origin/main` added Mouse, Privacy, Region, and Online +Accounts destinations while this feature was in review. Merge commit `4ef2f01` +preserves those routes and the newer Settings navigation architecture, keeps +the stable `services` route rendered by `HealthPage`, and leaves +`ServicesPage.qml` retired. Its useful Fedora handoffs for Users, Sharing, +Colour profiles, and Digital wellbeing now live in the boundary-last System +Health card alongside the existing network handoff, with focused static and +isolated runtime coverage. + +**Live-audit handoff:** Per the integration brief, this task does not reload the +daily-driver Quickshell, invoke a live repair, or run the read-only live +doctor/IPC comparison. Those checks remain for the controller after code review. + **Files:** - Modify: `config/dot/hypr/DESKTOP-PARITY.md` - Modify: `config/dot/quickshell/modules/settings/README.md` @@ -507,7 +520,7 @@ git commit -m "Add bounded Panama recovery actions" - Consumes: the complete feature and existing regression suite. - Produces: current user documentation, a redacted live health snapshot, and final verification evidence. -- [ ] **Step 1: Document boundaries and entry points** +- [x] **Step 1: Document boundaries and entry points** Document `Panama: Check System Health`, Settings → System Health, the degraded-only bar indicator, `panama-doctor --summary`, the no-`sudo`/no-package-install boundary, and the fact that GNOME/Fedora tools remain responsible for generic system configuration. @@ -525,7 +538,16 @@ for test in tests/quickshell/*contract.sh; do "$test"; done for test in tests/hypr/*contract.sh; do "$test"; done ``` -Expected: every command exits 0; Quickshell tests report 58 contracts after the three new contracts land. +Expected: every command exits 0. After the Settings parity merge, the current +inventory is 65 Quickshell contracts and 2 Hyprland contracts (the original +pre-merge estimate was 58). + +Integration result: syntax and all focused Health/Settings contracts pass. Two +complete serial Quickshell runs each passed 63/65, but failed on different +order-sensitive contracts. Run one failed Displays and Settings Hyprland Write; +run two failed Focus Session and Health Service. Each failed contract passed +immediately when rerun alone. Hyprland contracts passed 2/2. No out-of-scope +test or service code was changed to hide this suite-order interference. - [ ] **Step 3: Run a redacted live read-only comparison**