The machine now carries its own manual for AI hands
Claude-Session: https://claude.ai/code/session_01Ms2FbjQy31TVf3CEvQhGM8
This commit is contained in:
Gabriel Brown
@@ -0,0 +1,63 @@
|
||||
---
|
||||
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` — verify the desktop's contracts without hijacking the session
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: panama-sudo
|
||||
description: Use whenever a command needs root on a Panama machine — any sudo, pkexec, or privileged system change. Panama routes privilege through a wrapper that shows the user your reason beside the password prompt.
|
||||
---
|
||||
|
||||
# panama-sudo
|
||||
|
||||
Never run bare `sudo` or `pkexec` on a Panama machine. Use:
|
||||
|
||||
```sh
|
||||
panama-sudo --reason "why this needs root" -- command args…
|
||||
```
|
||||
|
||||
`--reason` must be the first argument; the `--` separator is optional. The reason is displayed on
|
||||
the desktop's own polkit prompt **beside** — never instead of — polkitd's description of the
|
||||
action, because anything can claim any reason. That is the trust model, and it shapes how you
|
||||
write the reason: state what the command does, not an assurance that it is safe.
|
||||
|
||||
- Good: `--reason "Install the fwupd package so firmware updates can be checked"`
|
||||
- Bad: `--reason "Safe maintenance task"`
|
||||
|
||||
With no `--reason`, no running shell, or no `qs` on PATH, it degrades to plain `pkexec` — so it
|
||||
is always the right call, even in a TTY or a broken session.
|
||||
|
||||
One reason per privileged action. Do not batch unrelated root commands behind a single vague
|
||||
reason; the user approves what the prompt says, and the prompt should say everything.
|
||||
|
||||
House precedent: `bin/panama-migrate` documents the rule — root work goes through
|
||||
`panama-sudo --reason "..."`, never bare sudo — and every shipped migration follows it.
|
||||
Reference in New Issue
Block a user