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