Document Panama health and recovery

2026-08-18 11:36:06 -04:00
parent 4ef2f01baa
commit f8e7512e01
3 changed files with 74 additions and 2 deletions
@@ -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

@@ -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.
@@ -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**