Panama/skills/panama-desktop/SKILL.md

name, description

name	description
panama-desktop	Use when interacting with the desktop on a Panama machine (Hyprland + the Panama Quickshell shell) during any task — opening settings, checking system health, taking screenshots, toggling Do Not Disturb, launching or focusing applications, or diagnosing audio, network, or display questions.

panama-desktop

This machine runs Panama: Hyprland with a shell that replaces GNOME's bar, dock, notifications, settings, and lock screen. The desktop has a command surface built for exactly what you are about to do — use it instead of poking at processes and config files.

Reading the machine

panama doctor prints a JSON health snapshot (schemaVersion 1): a summary with an overall status and per-check counts, and checks[] with {id, group, title, status, detail, action}. Groups: desktop-foundation, input-media, integrations, panama-tools. Check ids follow group.name (desktop.quickshell, input.pipewire, integration.kdeconnect, panama.updates — the full list is in any snapshot). Useful forms:

• panama doctor --summary — one human line
• panama doctor check <id> — a single check, same envelope
• panama doctor --repair <id> — run a check's repair; exit code is the verdict

It reports what is actually running, not what was installed — trust it over ps archaeology.

Driving the desktop

panama-action <verb> (on PATH via ~/.config/quickshell/scripts/panama-action) is the stable boundary for desktop actions. Verbs: control-center, notifications, calendar, clipboard, overview, settings, settings-page <id>, dock-pin, health, dnd, caffeine, night-light, focus-start, focus-end, capture, intelligence, screenshot, microphone, gallery, restart-shell.

Beneath it sits qs ipc call <target> <function> — the shell's full IPC surface, one IpcHandler per target in config/dot/quickshell/shell.qml (status verbs are free to call; anything else changes live state). Prefer panama-action when a verb exists.

Other tools that beat raw commands:

• panama-launch --class '<regex>' -- cmd… — focus the window if it exists, launch otherwise
• panama-sudo --reason "why" -- cmd… — root work; load the panama-sudo skill first
• panama update — bring the machine current (pull, repairs, unattended stages); asks nothing
• panama test --safe — run only contracts classified as hermetic in tests/contracts.manifest

A plain panama test prompts in a terminal before it starts non-hermetic contracts. Automation must grant each required capability with a repeatable --allow, such as panama test --allow live-host updates. Each contract has a 180-second outer timeout by default, and failures print captured stdout and stderr.

Settings

Open a page for the user with panama-action settings-page <id> (leaf ids like displays, sound, connectivity; docs/settings.md in the repo documents every key and page).

Change values through the Settings window or the shell's IPC — do NOT hand-edit ~/.config/panama/settings.json while the shell runs: the shell's writes merge-and-win for any key it has touched, so your edit silently loses. The file is the user's to read and back up, not an API.

Where state lives (read, don't write)

• ~/.config/panama/settings.json — every setting; also read by the Hyprland Lua config
• $XDG_STATE_HOME/panama/ — generated idle/lock configs, settings backups, migration markers
• The repo itself is at ~/.local/share/Panama (or $PANAMA_PATH), and ~/.config entries are symlinks into it — a change to either is a change to both

If you find yourself editing files under ~/.config/quickshell or ~/.config/hypr, you are editing the Panama repository on a live desktop — stop and load the panama skill first.