78 lines
4.3 KiB
Markdown
78 lines
4.3 KiB
Markdown
---
|
|
name: panama-desktop
|
|
description: 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`
|
|
|
|
For a new machine, use the complete verified bootstrap command in `README.md`.
|
|
Desktop and server installs use the same commit-addressed `boot` file and
|
|
SHA-256; server adds only `--server`. Do not replace that URL with a branch or
|
|
pipe its response into Bash. `boot` refuses missing or malformed pins, a boot
|
|
digest mismatch, and any dirty, divergent, fetch-failed, or mismatched existing
|
|
checkout. Use `panama update` after installation.
|
|
|
|
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,
|
|
which a positive `PANAMA_TEST_TIMEOUT_SECONDS` value overrides. Failures print captured stdout
|
|
and stderr. Successful stdout stays quiet. Successful stderr is surfaced as a warning.
|
|
|
|
## 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.
|