WIP: Paused over-hardening fix wave (boot checkout verification, double-read package manifest)

Docs: Record signed Terra bootstrap proof
Test: Prove verified bootstrap boundaries
2026-09-17 11:44:01 -04:00 · 2026-08-27 11:13:59 -04:00 · 2026-08-27 10:44:14 -04:00 · 2026-08-27 10:14:55 -04:00 · 2026-08-27 10:06:13 -04:00 · 2026-08-27 09:48:28 -04:00
863 changed files with 115310 additions and 7389 deletions
@@ -0,0 +1,236 @@
+# Panama server role: headless installs and versioned containers
+
+2026-08-25. Designed with Gib across two interview rounds; every decision below
+was made explicitly, none inferred.
+
+## Goal
+
+Panama becomes the one repo for every Fedora machine Gib runs. A desktop gets
+what it gets today. A server — a Hetzner VPS, a future home server — gets the
+same shell environment (bash profile, prompt, tmux-on-ssh, agents) minus
+everything that needs a screen, plus rootless podman, systemd user units, and a
+versioned catalog of compose services that `panama server enable` brings up.
+The repo stays public; secrets never enter it.
+
+## Decisions of record
+
+| Decision | Choice |
+|---|---|
+| Repo | One public monorepo. No companion repo. `.gitignore` + a secrets contract keep it safe |
+| Role | Asked first in the interview (`desktop` / `server`), persisted to `~/.local/state/panama/role`; `--server` on `boot`/`install` presets it |
+| Layout | Top-level `server/`, services under `server/containers/<Name>/` (TitleCase, matching junior) |
+| Tracked per service | `compose.yml`, `podman-<name>.service`, `.env.example`. Nothing else |
+| `~/Server` | Real directories. Only `compose.yml` is symlinked into them; units symlink into `~/.config/systemd/user/`. Live `.env` and data stay outside the repo tree entirely |
+| Data dirs | Standardized to `./data/`, applied per service at cutover (a stop/rename/start), never at import |
+| Enablement | `panama server` subcommand family, not the interview |
+| Units | Checked in per service (they legitimately differ), installed as symlinks so edits flow with `panama update` |
+| Updates | `panama update` relinks and `daemon-reload`s but never restarts a running service; it names services whose definitions changed |
+| Nightly image updates | junior's `update-containers.sh` + `podman-update.timer` adopted into the repo (it replaced watchtower for cause) |
+| Codex | Installed everywhere, same pattern as Claude Code |
+| Ports | 80/443/81 only. Anything else is opened by hand and documented in the service's folder |
+| VPS bootstrap | `boot` run as root walks user-creation/keys/sshd-hardening, each step skipped when already true, then re-runs as the user |
+| Out of scope | server.gib (docker; translate later), backup and verify-rootless (own design later), cutover of junior's live services (later, per service) |
+
+## 1. Machine role
+
+- New interview question, asked first: "What is this machine?" — `desktop` or
+  `server` via `gum choose`. `./install --server` (and `boot --server`) records
+  the answer without asking.
+- Persisted to `~/.local/state/panama/role`, plain text, one word. This is the
+  first durable answer Panama keeps, and deliberately so: the transient-answers
+  principle exists to keep *personal* data out of durable paths, and a machine
+  role is a fact about the machine. `install`, `panama update`, `panama doctor`
+  and future migrations read it. A machine with no role file is a desktop —
+  every machine that predates this work is one.
+- On role=server the interview skips: hardware probes (NVIDIA, Secure Boot,
+  firmware — and their bootstrap tools; only `gum` is bootstrapped), the
+  debloat question, and the extras checklist. It keeps: hostname, git
+  identity, gh sign-in, SSH key, user-content.
+
+## 2. Stages by role
+
+Role=desktop is exactly today's behavior. Role=server runs:
+
+| Stage | Server behavior |
+|---|---|
+| `install-packages` | Core + server lists (§3). No flatpaks, no COPRs, no desktop repos. Claude Code and Codex install for both roles |
+| `link-dotfiles` | Universal dot dirs only: `btop`, `nvim`, `ohmyposh`, `tmux`, `vim`, `panama`. Desktop-only (everything else: `hypr`, `quickshell`, `kitty`, `ghostty`, `espanso`, `gtk-*`, `uwsm`, `vicinae`, `wofi`, `xdg-desktop-portal`) is skipped via an explicit classification list in the stage — a new dot dir must be classified or the contract fails. Bash profile links as today; Firefox/wallpaper/cursor seeding skipped |
+| `link-user` | Unchanged (SSH aliases and agent rules are exactly what a server wants) |
+| `setup-identity` | Unchanged |
+| `setup-server` (new) | §4 |
+| `link-server` (new) | Creates `~/Server`, then delegates to `panama-server relink` so link repair has one owner |
+| Skipped | `link-skills` (all three shipped skills are desktop-specific today; revisit when a server skill exists), `change-settings`, `link-vicinae-scripts`, `install-hardware` |
+
+Migrations run on servers too — they are self-guarding no-ops where they do
+not apply. `panama doctor` learns the role: on a server it reports service
+health via `panama-server status` instead of probing desktop units.
+
+## 3. Package restructure
+
+`setup/packages/` gains `core-packages` (both roles) and `server-packages`;
+`initial-packages` keeps what is desktop-only. Nothing is added or dropped for
+desktops — the union of core + desktop lists equals today's set.
+
+- **core-packages**: awk, bat, btop, curl, dnf5-plugins, eza, fontconfig, fzf,
+  gh, git-all, gum, jq, neovim, oh-my-posh, openssh, openssl, podman,
+  podman-compose, python3-dnf, ripgrep, tmux, unzip, wget, zoxide.
+  (`podman` moves here from development-packages; `podman-compose` is what
+  provides `podman compose` on junior — verified, 1.6.0.)
+- **server-packages**: nvm (Node via nvm, as on desktop — agents and MCP
+  servers want it, and Codex installs through npm).
+- **initial-packages** (desktop-only remainder): cargo, rustup, flatpak, fwupd,
+  kitty, ksshaskpass, libselinux-utils, pciutils, python3-neovim,
+  wireguard-tools, vim-X11 — plus everything else currently there that the
+  core list did not claim.
+- Codex CLI: installed in `install-packages` beside the Claude Code step —
+  skip when `codex` is on PATH, `npm install -g @openai/codex` (after nvm/node
+  is available), soft-fail like Claude Code does.
+- The package-hash mechanic in `install` is untouched; new files under
+  `-maxdepth 1` join the hash automatically.
+
+## 4. `setup-server` stage
+
+Idempotent, like every stage; each item checks before acting:
+
+1. `loginctl enable-linger $USER`.
+2. `/etc/sysctl.d/99-rootless-ports.conf` → `net.ipv4.ip_unprivileged_port_start=80`,
+   applied with `sysctl --system` (junior already has exactly this file).
+3. firewalld: open 80, 443, 81 (NPM admin portal), permanent + runtime.
+   Nothing else — reverse-proxy philosophy, ports open only when unavoidable.
+4. `podman network create nginx-bridge` if absent (every compose expects it,
+   `external: true`).
+5. Nightly image updates: `update-containers.sh` is adopted into the repo as
+   `server/scripts/update-containers` (no `.sh`, per repo rule — junior's copy
+   is imported and its `ExecStart`/log paths updated), with
+   `server/systemd/podman-update.service` and `.timer` symlinked into
+   `~/.config/systemd/user/` and the timer enabled. Logs go to
+   `~/Server/logs/` as today.
+
+## 5. The `panama server` command
+
+`bin/panama-server`, surfaced as `panama server <verb>` (README's subcommand
+table and its contract update with it):
+
+- `list` — every service in `server/containers/`, with enabled/active state.
+- `enable <Name>` — create `~/Server/<Name>/`; symlink `compose.yml`; seed
+  `~/Server/<Name>/.env` from `.env.example` when the example exists and the
+  live file does not; if the seeded `.env` still contains placeholder values,
+  stop there and say what to fill in — do **not** start; otherwise symlink the
+  unit, `daemon-reload`, `enable --now`.
+- `disable <Name>` — `disable --now`, remove the unit symlink,
+  `daemon-reload`. `~/Server/<Name>` and its data are never touched.
+- `status [<Name>]` — unit state plus `podman compose ps` per service.
+- `relink` — for every service whose unit symlink exists: refresh both
+  symlinks, `daemon-reload`, and report services whose definitions changed
+  since the last run (so the operator restarts deliberately). Called by the
+  `link-server` stage and by `panama update` on role=server.
+
+Live `.env` files live in `~/Server/<Name>/`, not in the repo tree — the repo
+carries only `.env.example`. `.gitignore` still covers `.env` everywhere under
+`server/` as belt and braces.
+
+## 6. VPS bootstrap (`boot` as root)
+
+`boot` gains a root path. When `EUID == 0`, before anything else, walk these
+steps, each checked and skipped when already true:
+
+1. Ask for a username (default `gib`). Create it with `wheel` if absent; if it
+   exists, use it.
+2. Ensure the user has a password (needed for sudo) — `passwd` interactively
+   if none is set.
+3. Copy root's `authorized_keys` only after OpenSSH parses every key line. The
+   destination directory and file are created as the target UID at `0700/0600`
+   and revalidated before hardening is available.
+4. Offer sshd hardening (yes/no, default yes): atomically install
+   `/etc/ssh/sshd_config.d/00-panama.conf` with `PermitRootLogin no`,
+   `PasswordAuthentication no`, and `KbdInteractiveAuthentication no`. Run
+   `sshd -t` plus effective root/target `sshd -T -C` checks before reloading the
+   detected unit. Restore a prior regular file with metadata on failure. A
+   missing unit or unsupported existing drop-in leaves SSH unchanged and
+   bootstrap continues. The later binding transaction design owns the details.
+5. Move/clone the checkout under the user's home, chown it, and re-exec
+   `install --server` as that user.
+
+Run as a normal user, `boot` behaves exactly as today (plus passing `--server`
+through).
+
+## 7. Importing junior's services (the first population)
+
+A one-time operation, performed against junior over SSH, that **never stops,
+starts, or restarts anything**. For each dedicated compose dir:
+
+1. Copy `compose.yml` into `server/containers/<Name>/`.
+2. Take the **installed** unit (`~/.config/systemd/user/podman-<name>.service`)
+   as truth; diff against the copy in the service dir and flag any divergence.
+3. Move inline secrets out: secret-bearing values in the repo copy of
+   `compose.yml` become `${VAR}` interpolations; extracted values are written
+   to `~/Server/<Name>/.env` **on junior** (inert until cutover — the live
+   compose still carries them inline); `.env.example` with placeholder values
+   is committed. Services already using `.env`/`env_file` get an
+   `.env.example` generated from the live `.env` with values blanked.
+4. Verify without touching the stack: `podman compose config` rendered from
+   the repo copy (with the live `.env`) must match the render of the live
+   compose. Volume paths are kept **verbatim** at import (`volumes/`,
+   `volume/`, `pg_data/` and all) so this diff can be exact; the `data/`
+   standardization happens per service at cutover.
+5. Commit. The secrets contract (§8) gates every one of these commits.
+
+**Import list (23):** Adminer, Agentchat, Authentik, Beszel, CalCom,
+ConvexMonorepo, Documenso, Gitea, Infisical, ISponsorBlockTV, LashAddict, N8n,
+Nginx_Proxy_Manager, Penpot, Portainer, PostgreSQL, Rustdesk, Spoon, StPeteIT,
+Tools, Uptime, UseSend, Vaultwarden. CalCom, Documenso, Penpot and N8n are
+currently parked (dir present, unit not active) — imported anyway, noted as
+parked in the catalog.
+
+**Excluded:** Watchtower (retired — replaced by the update timer after it took
+gitea down; its dir stays on junior until cleanup), Completeuphoria,
+sierraandtyler, Bang (source checkouts deployed by CI from their own repos —
+Panama owning a second copy of their compose would drift), `ci/`, `logs/`,
+and junior's loose scripts other than `update-containers.sh` (§4).
+
+**Cutover** (per service, later, not this work): stop → rename the volume dir
+to `data/` and update the repo compose to match → replace live compose with
+the symlink, installed unit with the symlink → `daemon-reload` → start →
+verify. Ten minutes a service, done when Gib chooses, favoring quiet hours.
+
+## 8. Contracts and docs
+
+New `tests/server/`, same discipline as the rest:
+
+- `compose-secrets-contract` — fails when any tracked file under `server/`
+  contains an inline secret-looking value (the `user-content-contract`
+  pattern), when `.gitignore` stops covering `.env` under `server/`, or when
+  `git ls-files` shows a tracked `.env`.
+- `containers-shape-contract` — every `server/containers/<Name>/` carries
+  `compose.yml` + `podman-<name>.service`; every unit's `WorkingDirectory` is
+  `%h/Server/<Name>`; every `${VAR}` used in a compose file appears in that
+  service's `.env.example`.
+- `panama-server-contract` — throwaway `HOME`, stubbed `systemctl`/`podman` on
+  PATH: `enable` creates the right symlinks and seeds `.env`; placeholder
+  values block start; `disable` leaves data alone; `relink` reports changed
+  definitions.
+- `role-contract` — the interview asks role first, `--server` presets it, the
+  role file is written, stages filter correctly per role (via the stage
+  scripts' static/stubbed seams).
+- `dotfile-classification-contract` — every dir in `config/dot/` appears in
+  exactly one of link-dotfiles' universal/desktop lists.
+- README: layout section gains `server/`, the subcommand table gains
+  `panama server`, the pinned contract count moves — `readme-contract` and the
+  interview/link-dotfiles contracts that assert today's behavior update in the
+  same change.
+
+## Phasing
+
+1. **Role plumbing** — interview question, role file, `--server`, package
+   split, stage filters, `setup-server`, boot's root path.
+2. **Server skeleton** — `server/` tree, `panama-server`, `link-server`,
+   update-timer adoption, contracts, README/docs.
+3. **Import** — junior's 23 services into `server/containers/` per §7.
+4. **Later, separately** — per-service cutover on junior; backup and
+   verify-rootless design; server.gib docker→podman translation; a real
+   end-to-end test on a fresh VPS.
+
+Testing note: contracts for phases 1–2 run with stubs and throwaway HOMEs, but
+per standing practice all suite runs batch at the end of the session with
+Gib's go-ahead. Phase 3 touches junior only with read commands plus the inert
+`.env` writes described in §7.
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(coredumpctl list:*)",
+      "Bash(coredumpctl info:*)",
+      "Bash(journalctl:*)",
+      "Bash(rpm -q:*)",
+      "Bash(panama doctor:*)"
+    ]
+  }
+}
@@ -0,0 +1,133 @@
+---
+name: panama
+description: Use when working on the Panama repository itself — editing anything under config/, setup/, bin/, tests/, or the Quickshell shell and Hyprland Lua it ships. Covers the live-desktop hot-reload rules, the contract-test discipline, the fixture seams, and where the real documentation lives.
+---
+
+# panama
+
+You are editing a running desktop, not a codebase that gets deployed later. Every dotfile in this
+repository is symlinked into `~/.config`, so a save is live the moment it lands. That single fact
+drives every rule below.
+
+Read before large work, in this order:
+
+- `README.md` — layout, the `panama` command, how installing and updating work
+- `config/dot/hypr/README.md` — the compositor config is **Lua, not hyprlang**; read "The one
+  thing to know first" and "Never use `hyprctl keyword`" before touching it
+- `config/dot/quickshell/modules/settings/README.md` — adding a setting, setting ownership,
+  "Things that will bite you", and where state lives; the most load-bearing document here
+- `docs/settings.md` — generated reference for every settings key (never edit by hand)
+
+## The live-desktop covenant
+
+Editing `config/dot/quickshell/**` hot-reloads the live shell on every save.
+
+1. Every save must leave valid QML. An intermediate broken save is a broken desktop, not a broken
+   build. Convert a component and its body in ONE edit, never two.
+2. After each batch of saves, check the journal for errors AND "Unable to assign" warnings:
+   `journalctl --user -u panama-quickshell.service --since '-2 minutes' --no-pager`
+3. Every `.qml` file in `config/dot/quickshell/modules/*` must be registered in that directory's
+   `qmldir` in the same save batch. An unregistered component fails the whole configuration and
+   takes down the bar, dock, and settings together. `tests/quickshell/qmldir-registration-contract`
+   is pure file inspection — run it before the change lands.
+4. Never `qs kill` from a copied configuration: Quickshell derives the shell ID from config
+   content, so a content-identical harness can share the live shell's ID and kill the desktop.
+   Harnesses use a distinct entry file, `qs -p`, the PID from `qs list --all`, and `kill` that PID.
+5. Never `hyprctl keyword` — Lua-configured Hyprland refuses it, prints to stdout, and exits 0.
+   `hyprctl eval` also exits 0 on errors. The only proof a write landed is `hyprctl getoption`
+   reading it back. Batch `hyprctl reload` to one per verified change-set, and say when you do it.
+6. IPC: annotate every parameter and return type or Quickshell silently skips registration; never
+   duplicate an `IpcHandler` target — one silently shadows the other.
+7. In `config/dot/quickshell/config/PreferenceSchema.qml`, `readAs` describes the compositor's
+   ANSWER shape, not the setting's; a wrong one makes every successful write look rejected.
+8. No continuously repainting animations (pulse, shimmer, spinners) — they peg the GPU on
+   high-refresh displays.
+9. `hyprlock.conf`, `hypridle.conf`, `hyprpaper.conf`, `hyprtoolkit.conf` never moved to Lua. Do
+   not "fix" them. Do not install a notification daemon — the shell is one.
+10. Scripts carry no `.sh` extension (shebang + `chmod +x`), with one deliberate exception:
+    `migrations/*.sh`, which `bin/panama-migrate` globs. No secrets under `user/` — it is
+    world-readable and `tests/setup/user-content-contract` greps for key material.
+
+## The contract discipline
+
+Every executable contract under `tests/` is classified in `tests/contracts.manifest`. The rules:
+
+- `panama contracts <file>` names the contracts that mention a file; run those after touching it.
+- During a desktop session, run `panama test --safe [pattern]`. `--safe` selects only contracts
+  classified as `hermetic`.
+- A plain full run prompts in a terminal before any selected non-hermetic contract starts. In
+  automation, grant every required capability with repeatable flags, for example
+  `panama test --allow live-compositor --allow live-desktop keybinds`.
+- Each contract has a 180-second outer timeout by default. Override it with a positive
+  `PANAMA_TEST_TIMEOUT_SECONDS` value. Failures print the contract's captured stdout and stderr.
+  Successful stdout stays quiet. Successful stderr is surfaced as a warning.
+- Contracts run directly too: `tests/setup/interview-contract`.
+- After changing `PreferenceSchema.qml` or `services/SettingsRoutes.qml`, regenerate:
+  `config/dot/quickshell/scripts/panama-settings-docs` (writes `docs/settings.md`) and
+  `config/dot/quickshell/scripts/panama-settings-commands` (writes the launcher deep links).
+  Both take `--check`; `tests/quickshell/settings-docs-contract` fails when stale.
+- `README.md` pins the contract count and the `panama` subcommand list
+  (`tests/setup/readme-contract`); adding a contract or subcommand means updating it.
+
+## Seams for testing
+
+Helpers are built hermetic: validated inputs, JSON out, secrets on stdin only (never argv).
+Contracts reach them through env seams — `PANAMA_NETWORK_HELPER`, `PANAMA_FINGERPRINT_FIXTURE`,
+`PANAMA_EXTRAS_DIR`, and the `PANAMA_*_STATIC_ONLY` family that cuts a contract to its
+file-inspection half. Prefer exercising a helper through its contract's stubbed PATH over running
+it against the real system.
+
+## Safety idioms (contract-enforced)
+
+- Destructive actions are two-stage: `ConfirmAction` with a unique `actionId`, arbitrated through
+  `ShellState.armedConfirm` — one armed confirm app-wide. Danger tone marks only the confirming
+  press.
+- Failures render through `ErrorRow`; honest empty states through `NotMeasuredRow` with a
+  `because:`; paragraph-length notes through `SettingsNote`.
+- Stored user actions (custom shortcuts, gestures, window rules) are DATA — an enum kind and a
+  validated target resolved through whitelist tables in `config/dot/hypr/actions.lua`. Nothing in
+  `~/.config/panama/settings.json` may ever be an executable command; the contracts
+  (`tests/quickshell/settings-idiom-contract`, `tests/quickshell/keybind-rebind-contract`) pin all
+  of this.
+
+## Root work
+
+Never bare `sudo`. Load the `panama-sudo` skill first. Migrations already follow the rule.
+
+## Initial bootstrap trust
+
+Use the complete command in `README.md` for a new machine. It downloads `boot`
+from the documented commit URL into a private temporary directory, enforces the
+documented curl time and byte limits, verifies the committed blob with
+`sha256sum -c`, and passes both pins to the verified script. Desktop and server
+bootstrap use the same commit and digest. Never substitute a branch URL, pipe a
+response into Bash, or invent a newer pin from an uncommitted file.
+
+`boot` validates the full lowercase commit and SHA-256 before Git or install. A
+fresh destination fetches only that revision and creates a tracked local `main`
+after HEAD matches. An existing checkout must be clean and an ancestor of the
+requested revision; it advances with fast-forward only. Dirty, divergent,
+fetch-failed, or mismatched checkouts stop without reset or install. Once Panama
+exists, use `panama update` for normal updates.
+
+`boot --server` is the one exception where a new Fedora VPS may begin as root.
+Before it offers SSH hardening, it copies a safe root key when possible or
+verifies the target key. The target user's `.ssh` must be owned by that user at
+`0700`, and `authorized_keys` must be owned by that user at `0600`. Without a
+verified target key, SSH hardening is unavailable and the bootstrap continues.
+Every non-comment key line must parse with `ssh-keygen`. Root-key destination
+creation and writing run as the target UID, followed by the same owner, mode,
+and key checks. Do not replace that with root writes or assume the user's
+primary group matches the username.
+
+Accepted hardening uses atomic same-directory `00-panama.conf` with exactly
+`PermitRootLogin no`, `PasswordAuthentication no`, and
+`KbdInteractiveAuthentication no`. A pre-existing symlink or non-regular
+object makes hardening unavailable, as does a missing SSH unit. Panama runs
+`sshd -t`, then checks effective root and target-user policy with `sshd -T -C`
+before reloading the detected unit. Validation or reload failure restores a
+prior regular file with its metadata before it retries validation and reload.
+Failed recovery stops the handoff with instructions that distinguish a prior
+file from no prior file. The fixture contracts also cover declined hardening
+and interrupted preparation. `panama test --safe` never reloads a live daemon,
+so it is not live-host proof.
@@ -1,5 +1,15 @@
-# Ignore bash environment variables.
+# Ignore bash environment variables, and the lock its writer takes.
 /config/bash/env
+/config/bash/.env.lock
+# Server secrets and state never enter the repo: live .env files belong in
+# ~/Server/<Name>/ (only compose.yml is symlinked back here), and data/ is
+# the bind-mount convention. Ignored anyway as a seatbelt -- the repo is
+# public, and tests/server/compose-secrets-contract is the check that this
+# line still exists.
+/server/containers/**/.env
+/server/containers/**/data/
+# Personal espanso triggers (name, email), seeded per-machine by setup-identity.
+/config/dot/espanso/match/identity.yml
 # Ignore backups of old config files
 /config/old
 # Ignore Wireguard config of course!
@@ -19,14 +29,20 @@ __pycache__/

 # Generated from the color scheme; machine state, not configuration.
 /config/dot/gtk-3.0/settings.ini
+/config/dot/gtk-3.0/bookmarks
 /config/dot/gtk-4.0/settings.ini
 /config/dot/tmux/current-theme.conf
 /config/dot/hypr/hyprlock.conf
+# The Firefox chrome override sheet, rendered from the active theme. It sits
+# beside custom.css because chrome/ is symlinked into the profile as one
+# directory; custom.css imports it and stays the file a person edits.
+/config/firefox/chrome/panama-theme.css
+/config/firefox/chrome/panama-theme.css.tmp

-# Build products of the Vicinae extension. The source is the repository's; the
-# dependency tree and the bundle it produces are machine state, rebuilt by
-# `panama apps`.
+# Build products of the Vicinae extension. The source and reviewed lockfile are
+# in the repository; the dependency tree and bundle are machine state.
 /config/local/share/vicinae/extensions/*/node_modules/
 /config/local/share/vicinae/extensions/*/dist/
 /config/local/share/vicinae/extensions/*/build/
 /config/local/share/vicinae/extensions/*/package-lock.json
+!/config/local/share/vicinae/extensions/panama-search/package-lock.json
@@ -1,13 +1,99 @@
 # Panama

 Formerly Sunhat. A personal config for Fedora, with the intention of helping a
-user set up their Fedora system with one command.
+user set up their Fedora system with one checked command.

 ```sh
-git clone https://git.gbrown.org/gib/Panama.git ~/.local/share/Panama
-~/.local/share/Panama/install
+(
+set -euo pipefail
+bootstrap_commit=0d1841cf86975d52485c94c0caa5d1b67e5c54a1
+bootstrap_sha=fd8dcd70d1266da109972df346e3d85d1037f6f6e1942b0157064412ab892372
+bootstrap_dir="$(umask 077; mktemp -d)"
+trap 'rm -rf -- "$bootstrap_dir"' EXIT
+bootstrap="$bootstrap_dir/boot"
+curl --fail --location --connect-timeout 10 --max-time 30 --max-filesize 262144 \
+  --output "$bootstrap" \
+  "https://git.gbrown.org/gib/Panama/raw/commit/$bootstrap_commit/boot"
+printf '%s  %s\n' "$bootstrap_sha" "$bootstrap" >"$bootstrap_dir/boot.sha256"
+sha256sum -c "$bootstrap_dir/boot.sha256"
+PANAMA_BOOT_REVISION="$bootstrap_commit" PANAMA_BOOT_SHA256="$bootstrap_sha" \
+  bash "$bootstrap"
+)
 ```

+`boot` installs git if the machine lacks it, creates a verified checkout at
+`~/.local/share/Panama` (or `$PANAMA_PATH`), and hands off to `install`. It is
+deliberately small enough to read first. The command downloads one immutable
+`boot` blob into a private temporary directory, checks its SHA-256, then asks
+that verified script to fetch the same commit. A clean existing checkout may
+fast-forward to that exact revision. A dirty or divergent checkout, a failed
+fetch, or a revision mismatch stops before `install`; Panama never resets local
+work or falls back to whatever checkout happens to be present.
+
+Once a machine exists, the command that keeps it current is `panama update` —
+one command, and it never asks you anything:
+
+```sh
+panama update
+```
+
+It pulls, applies any repairs this machine has not had, and runs the stages
+below that need no answers. `./install` remains what it is: how a machine is
+built, and how you change an answer you gave.
+
+The first question the interview asks is what the machine is: a **desktop**
+gets everything below; a **server** — a VPS, a headless box — gets the same
+shell environment minus everything that needs a screen, plus rootless podman
+and the compose services in [`server/`](server/README.md). The answer is the
+one thing Panama records durably (`~/.local/state/panama/role`), because
+`panama update` asks nothing and still has to know. A fresh server skips the
+question entirely. It uses the same immutable boot blob and pins as the desktop
+command; only the final `--server` argument differs:
+
+```sh
+(
+set -euo pipefail
+bootstrap_commit=0d1841cf86975d52485c94c0caa5d1b67e5c54a1
+bootstrap_sha=fd8dcd70d1266da109972df346e3d85d1037f6f6e1942b0157064412ab892372
+bootstrap_dir="$(umask 077; mktemp -d)"
+trap 'rm -rf -- "$bootstrap_dir"' EXIT
+bootstrap="$bootstrap_dir/boot"
+curl --fail --location --connect-timeout 10 --max-time 30 --max-filesize 262144 \
+  --output "$bootstrap" \
+  "https://git.gbrown.org/gib/Panama/raw/commit/$bootstrap_commit/boot"
+printf '%s  %s\n' "$bootstrap_sha" "$bootstrap" >"$bootstrap_dir/boot.sha256"
+sha256sum -c "$bootstrap_dir/boot.sha256"
+PANAMA_BOOT_REVISION="$bootstrap_commit" PANAMA_BOOT_SHA256="$bootstrap_sha" \
+  bash "$bootstrap" --server
+)
+```
+
+That command also works from a brand-new VPS's **root** login. It creates or
+reuses your sudo-enabled user, then copies a safe root key when it can or
+verifies the target key before offering SSH hardening. A verified target key
+means the target user owns `.ssh` with mode `0700` and `authorized_keys` with
+mode `0600`. Every non-comment line in `authorized_keys` must be valid OpenSSH
+key material that `ssh-keygen` can parse. Root-key destination writes run as
+the target user, and Panama rechecks the resulting owner, modes, and keys. SSH
+hardening is unavailable without a verified target key or installed SSH unit,
+and the install continues without it. Declining hardening also leaves SSH
+unchanged.
+
+When you accept hardening, Panama uses an atomic same-directory drop-in named
+`00-panama.conf`, whose early filename gives it safer precedence. A pre-existing
+symlink or non-regular object makes hardening unavailable. The effective policy
+is exactly `PermitRootLogin no`, `PasswordAuthentication no`, and
+`KbdInteractiveAuthentication no`. Panama validates syntax with `sshd -t` and
+checks `sshd -T -C` for both root and target-user contexts before it reloads
+the detected SSH unit. If validation or reload fails, it restores the previous
+drop-in regular file with its metadata and validates and reloads that restored
+configuration. Recovery that cannot complete stops the handoff and prints the
+right manual command for either a prior file or no prior file. The fixture
+contracts test these branches. No real daemon reload runs under
+`panama test --safe`, so that suite is not live-host proof.
+
+After that, it hands off to a normal install as the new user.
+
 `install` asks its questions first and then runs the stages in `setup/scripts/`
 in order, without stopping again:

@@ -16,10 +102,28 @@ in order, without stopping again:
 | `interview` | Every prompt, before anything is installed. Answers last one run and are never written to a durable path |
 | `install-packages` | Repos (RPM Fusion, Terra, Hyprland COPR), the package lists in `setup/packages/`, then whichever optional categories were chosen |
 | `link-dotfiles` | Symlinks `config/dot/<name>` → `~/.config/<name>`, and seeds the wallpaper, cursor theme and Firefox chrome |
+| `link-skills` | Links the agent skills in `skills/` into `~/.claude/skills`, one per skill. Every machine gets these; personal ones link after and win a name clash |
+| `link-user` | Links the personal content in `user/` — agent instructions, SSH host aliases — but only on a machine that answered yes. See [user/README.md](user/README.md) |
 | `change-settings` | Copies `config/copy/` over `/`, applies gsettings, enables user services |
 | `link-vicinae-scripts` | Publishes the Vicinae script commands |
 | `setup-identity` | git config, `gh auth login`, an SSH key — whichever were asked for |
 | `install-hardware` | NVIDIA, Secure Boot enrollment, Fedora's extras, firmware — each only if it was asked for. Last, because enrollment and firmware are consumed at the next boot |
+| `setup-server` | Server role only: linger, unprivileged ports from 80, firewalld (80/443/81), the `nginx-bridge` network, and the nightly image-update timer |
+| `link-server` | Server role only: creates `~/Server` and refreshes the links of whatever services this machine has enabled |
+
+A server runs the shared stages plus its own two, and skips the rest —
+`link-skills`, `change-settings`, `link-vicinae-scripts` and
+`install-hardware` are desktop concerns. `link-dotfiles` links only the
+universal dot dirs there (bash, nvim, tmux, btop and tmux theming, the hook
+samples), and `install-packages` takes a short path: the core tools, nvm,
+Bun, Claude Code and Codex — no third-party repos, no desktop, no flatpaks.
+
+Then `panama migrate` applies any repairs this machine has not had yet. That is
+the half of an upgrade installing cannot do: the stages above only ever add, so
+nothing there can remove a file this repository stopped shipping or repair a
+symlink that now points nowhere. A fresh machine is marked as already caught up
+rather than having those repairs run against it, and a machine with work waiting
+is told at the next login rather than left to find out.

 The run ends with a health summary from `panama-doctor`, which reports what is
 actually running rather than what was attempted. It never fails the install: on a
@@ -53,23 +157,58 @@ the comments of the components themselves, because knowing what a thing was
 modelled on explains why it behaves the way it does.

 GNOME is not gone from the machine: `gnome-control-center` is a declared
-dependency, and Panama's own Settings hands off to it for the panels it
-deliberately does not own — Online Accounts, Color, Sound, Network, Keyboard,
-Privacy, Wellbeing, Accessibility, and System for users, date and time, region
-and remote desktop. The allow-list in
-[`services/SystemSettings.qml`](config/dot/quickshell/services/SystemSettings.qml)
-is what decides; anything not on it is a panel Panama owns itself.
+dependency, and two rows in Panama's own Settings still open it. Adding an
+online account goes through the provider's dialog, because the OAuth sign-in
+runs inside a library Fedora ships without a binding anything else can call.
+And Digital wellbeing — screen time and break reminders — is the one panel of
+GNOME's that still does something Panama does not. Everything else it used to
+hand over is a page here now, and
+[`tests/quickshell/gnome-handoff-contract`](tests/quickshell/gnome-handoff-contract)
+fails the build if a door back opens onto a panel Panama owns, because those
+rows kept working perfectly long after they stopped being true.
+
+Displays is one of the panels it owns, and the only one where a wrong answer
+can leave you unable to see well enough to undo it. So every change there is
+applied as one complete layout, read back from the compositor, and reverted
+after fifteen seconds unless you keep it — resolution, scale, rotation,
+position and primary display, and now color profile, bit depth, SDR
+brightness and saturation, and mirroring with them. Two of those opt out of
+part of that, for reasons rather than convenience. A per-display variable
+refresh rate override is applied but never verified, because `hyprctl` reports
+whether adaptive sync is live this instant rather than what was asked for. And
+a mirrored display's position is not asserted at all: the compositor stacks it
+on the display it mirrors and ignores the coordinates the rule carried, so
+holding it to them would make Keep permanently unavailable. Monitor brightness
+sits outside the transaction entirely — it is the panel's own backlight over
+DDC, and the buttons on the bezel change it behind our back.

 | Piece | What it is |
 |---|---|
 | `config/dot/hypr/` | Compositor config. **Lua, not hyprlang** — see its README |
 | `config/dot/quickshell/` | The shell: bar, dock, Continuum overview, Settings, Screen Intelligence, focus sessions, quick settings, notifications, screenshot UI |
 | `config/containers/` | Container definitions systemd runs as units — currently the speech-to-text server behind dictation |
-| `config/dot/vicinae/` | Raycast-style launcher, themed. Its commands live in `config/local/share/vicinae/` — script commands, and one compiled extension that adds web search with live suggestions |
+| `config/dot/vicinae/` | Raycast-style launcher, themed. Its commands live in `config/local/share/vicinae/` — script commands (settings deep links, power actions, projects, reminders, window switcher, kill process, SSH hosts, recent files, color picker), and one compiled extension that adds web search with live suggestions. File search, calculator, clipboard, and emoji are Vicinae's own |
 | `config/dot/uwsm/` | Session environment (see the uwsm caveat in the hypr README) |
 | `config/dot/wofi/` | Fallback launcher, in case the shell fails to start |
 | `config/dot/xdg-desktop-portal/` | Portal backend routing |

+New machines get a welcome card on first start, teaching the handful of keys
+that matter and reachable afterwards from the launcher. `SUPER + /` shows every
+shortcut the machine has, read from the live keymap so a rebind appears there
+without anything being kept in sync. Rebinding is Settings' job, and so is
+adding a shortcut of your own or assigning the four-finger touchpad swipes: an
+entry names an application, a shell action or a window move rather than
+carrying a command, so a hand-edited settings file can move a key but cannot
+make one run something arbitrary. Settings carries a
+[manual](config/dot/quickshell/manual/) written for the person using the
+desktop rather than the person building it, opening with a chapter for people
+arriving from GNOME, macOS or Windows.
+
+Laptops work: battery, charge limits, idle timings that differ on battery, and
+a closed lid that suspends when you are leaving and keeps working when you are
+docked. A desktop sees none of it, because every one of those surfaces hides
+when the hardware is absent.
+
 **Start here: [`config/dot/hypr/README.md`](config/dot/hypr/README.md)** — it
 covers the Lua migration, the uwsm environment gotcha, the HDR decision, the
 full keymap, and troubleshooting.
@@ -80,16 +219,23 @@ Log in as **"Hyprland (uwsm-managed)"**, not plain "Hyprland".

 ```
 bin/            Small user-facing commands on PATH; `panama` is the entry point
+migrations/     One repair per file, for machines installed before a change
 config/
  bash/         .bashrc, aliases, env (env is gitignored)
  copy/         Files copied verbatim over / (needs sudo)
-  dot/          Symlinked into ~/.config
+  dot/          Symlinked into ~/.config; quickshell/manual/ is the manual
+                Settings renders
  firefox/      Vendored Firefox chrome, linked into the browser profile
  containers/   Quadlets, linked into ~/.config/containers/systemd
  local/        Icons, the cursor theme, and the launcher's commands and
                extensions, linked into ~/.local/share
  old/          Backups of whatever was replaced (gitignored)
  wallpapers/   Copied into ~/Pictures/Wallpapers when absent
+server/         The server role: compose services (one directory per
+                service), the nightly image updater, and its units. See
+                server/README.md
+skills/         Agent skills for operating this desktop, linked into
+                ~/.claude/skills
 setup/
  apps/         Applications built from source, one file each
  lib/          Shared by more than one stage; the extras catalog reader
@@ -101,14 +247,26 @@ docs/           Settings reference, and the design specs behind the work

 ## Tests

-131 of them, under `tests/`. Run the lot, or a subset by pattern:
+188 of them, under `tests/`. `tests/contracts.manifest` classifies every
+contract by the capabilities it needs. Run the hermetic set, or grant a
+specific external capability when automation needs it:

 ```sh
-panama test           # everything
-panama test dock      # just the ones matching "dock"
+panama test --safe
+panama test --allow live-host updates
+panama test --allow live-compositor keybinds
+PANAMA_TEST_TIMEOUT_SECONDS=300 panama test --safe
 tests/setup/interview-contract   # or one directly; they are plain executables
 ```

+`--safe` means hermetic contracts only. A plain full run prompts in a terminal
+before it starts any non-hermetic contract. Automation cannot answer that
+prompt, so it must grant every required capability with a repeatable `--allow`.
+Each contract has a 180-second outer timeout by default. Set
+`PANAMA_TEST_TIMEOUT_SECONDS` to a positive integer to override it. When a
+contract fails, the runner prints its captured stdout and stderr. Successful
+stdout stays quiet. Successful stderr is surfaced as a warning.
+
 They are called contracts rather than unit tests because that is what they are:
 each one pins a decision that was expensive to get right and is cheap to undo by
 accident. Most read or measure the real thing — launching a shell to measure a
@@ -121,6 +279,8 @@ been ones that source text looked fine for.
 tests/setup/       The installer: the interview, package lists, hardware, extras
 tests/quickshell/  The shell and its settings pages
 tests/hypr/        The compositor config
+tests/server/      The server role: the service catalog's shape, the secrets
+                   rule that keeps a public repo safe, and panama-server
 ```

 ## Projects
@@ -133,21 +293,44 @@ name it; **Open Project** lays it out again.
 Workspaces are recorded as positions rather than numbers, and opening a project
 claims free ones, so it never lands on top of what you are already doing. An
 application that refuses to open twice — Slack, Thunderbird, the browser — is
-moved into place rather than launched again. Saved layouts are listed on the
-Desktop settings page, which is also where they are removed.
+moved into place rather than launched again. Saved layouts are listed on
+Shell › Workspaces in Settings, which is also where they are removed.

 ## The `panama` command

 ```sh
-panama update     # review, commit and sync this repo
+panama update     # bring this machine up to date; asks nothing
+panama sync       # review, commit and push your changes to this repo
 panama edit       # open it in Neovim
 panama doctor     # what is actually running, not what was installed
-panama test       # every contract, or a subset by pattern
-panama upgrade    # re-run ./install from anywhere
+panama diagnose   # hand the health summary and recent errors to your agent
+panama test       # every contract, prompting before non-hermetic work
+panama test --safe        # hermetic contracts only
+panama test --allow live-host updates  # grant one capability to automation
+panama contracts <file>   # which contracts mention a file, and can they be run
+panama migrate    # apply repairs this machine has not had yet
+panama upgrade    # re-run ./install from anywhere, interview and all
 panama apps       # choose applications to install, by category
 panama app        # applications no repository carries; build one by name
+panama server     # the services a server runs: list, enable, disable, status
 ```

+`panama update` and `panama sync` are separate verbs on purpose. One acts on
+the machine, the other on the repository. A single command that chose between
+them by checking whether the working tree happened to be dirty would do a
+different job depending on state nobody can see — and, worse, would never
+update a machine belonging to somebody who had left a file edited.
+
+`panama update` stashes uncommitted work across the pull and restores it
+afterwards. If restoring conflicts it resets the checkout and leaves the work
+in the stash, saying so at the end of the run: every dotfile here is a symlink
+into this repository, so a conflict marker is not a thing to fix at leisure. It
+is live in `~/.config` the moment it is written.
+
+Only two things still need `./install`: a machine that does not exist yet, and
+an answer you want to change. Adding a package to a list you already have is
+`panama update`; adding an optional category is `panama apps`.
+
 `panama apps` is the optional-application catalog, opened after the fact. The
 interview offers the same categories during `./install`, whole; this picks a
 category and then the applications inside it, so a machine can acquire Slack in
@@ -159,6 +342,22 @@ package, a `flatpak:` line is a Flathub id, `| Name` gives the menu something
 readable, and an indented line belongs to the entry above it — which is how OBS
 carries its sixteen plugin extensions as one thing to tick.

+Hooks are the extension point: drop a script at `~/.config/panama/hooks/theme-set`
+and it runs whenever the color scheme changes, with the scheme and accent as
+arguments. Same for `post-upgrade` and `post-migrate`, and a `<name>.d/`
+directory beside each so several things can react without fighting over one
+file. A broken hook is reported and stepped over, never fatal. Samples are
+copied into place on install.
+
+`panama migrate` applies repairs an installed machine has not had yet. Safe to
+re-run: nothing is applied twice, and a machine with nothing waiting says so.
+
+`panama-sudo` is pkexec with a stated reason: `panama-sudo --reason "why" --
+command` shows the reason on Panama's password prompt, clearly labeled as an
+unverified claim beside polkitd's own action text — meant for agents and
+scripts, so the person typing the password learns why before they do. Without
+a reason, a running shell, or `qs` it behaves exactly like pkexec.
+
 `panama app` is deliberately not part of `./install`. Everything else Panama
 installs comes from dnf or Flathub; these are built from source because no
 packaged form exists, and a source build is slow, wants the network throughout,
@@ -170,6 +369,8 @@ the current upstream and reports a failure rather than working around it.
 Adding one is adding a file to `setup/apps/`, and the file has to say why the
 exception exists.

-None of the scripts in this repository carry a `.sh` extension. A shebang and
-the executable bit already select the interpreter, and the extension only
+No script in this repository carries a `.sh` extension, with one deliberate
+exception: each repair in `migrations/` is named `<timestamp>.sh`, because
+`panama-migrate` finds them by globbing exactly that. Everywhere else a shebang
+and the executable bit already select the interpreter, and the extension only
 becomes something to keep in sync — which it did not stay.
@@ -5,15 +5,24 @@
 # Author: Gabriel Brown
 #
 # Commands:
-#   update   Commit & sync local changes (or just pull if clean)
+#   update     Bring this machine up to date: pull, then install --upgrade
+#   sync       Review, commit & push local changes to this repo
 #   edit       Open the Panama repo in Neovim
 #   doctor     Report what is actually running on this machine
-#   test     Run every contract under tests/
-#   upgrade  Re-run the installer from anywhere
+#   diagnose   Hand this machine's health and recent errors to your agent
+#   test       Run contracts classified by tests/contracts.manifest
+#   contracts  Name the contracts that mention a given file
+#   upgrade    Re-run the installer from anywhere, interview included
+#   migrate    Apply repairs this machine has not had yet
 #   apps       Choose applications to install, by category
 #   app        Build and install an application that no repository packages
 #   help       Show this help
 #
+# update and sync are deliberately separate verbs. One acts on the machine, the
+# other on the repository, and a single command that guessed between them by
+# looking at whether the tree happened to be dirty would do a different job
+# depending on state nobody can see.
+#
 # Designed to grow: add new subcommands as cmd_<name> functions and
 # register them in the dispatcher / usage block below.

@@ -48,7 +57,7 @@ header(){ printf '\n%s%s%s\n'    "${MAGENTA}${BOLD}" "$*" "$RESET"; }
 # Ask a yes/no question. Returns 0 for yes, 1 for no. Default = no.
 confirm() {
  local prompt="$1" reply
-  printf '%s?%s %s %s[y/N]%s ' "${CYAN}${BOLD}" "$RESET" "$prompt" "$BOLD" "$RESET"
+  printf '%s?%s %s %s[y/N]%s ' "${CYAN}${BOLD}" "$RESET" "$prompt" "$BOLD" "$RESET" >&2
  read -r reply || true
  [[ "$reply" =~ ^[Yy]([Ee][Ss])?$ ]]
 }
@@ -64,20 +73,44 @@ ${BOLD}Usage:${RESET}
  $PROGRAM <command> [options]

 ${BOLD}Commands:${RESET}
-  ${GREEN}update${RESET}      Review, commit & sync local changes. If the working tree is
-              clean it simply runs 'git pull'.
+  ${GREEN}update${RESET}      Bring this machine up to date. Pulls, then runs the stages
+              that need no questions asked. The routine command; safe to
+              re-run, and it never asks you anything.
+  ${GREEN}sync${RESET}        Review, commit & push your changes to this repo. Uncommitted
+              work is committed before anything is fetched, so a moved
+              upstream is a rebase rather than a stash conflict.
  ${GREEN}edit${RESET}        Open the Panama repo in Neovim.
  ${GREEN}doctor${RESET}      Report what is actually running on this machine, rather
              than what was installed. Takes --summary for one line per check.
-  ${GREEN}test${RESET}        Run every contract under tests/. Give it a pattern to run
-              a subset: 'panama test dock' runs the ones matching 'dock'.
-  ${GREEN}upgrade${RESET}     Re-run ./install from anywhere. Safe: every stage is
-              idempotent and this is the documented upgrade path.
+  ${GREEN}diagnose${RESET}    Hand the health summary, the recent journal errors and
+              whatever you say is wrong to your coding agent, in a terminal.
+              Needs an agent chosen on Settings › System › Agents.
+  ${GREEN}test${RESET}        Run contracts classified by tests/contracts.manifest. Give it a
+              pattern to run a subset. --safe selects hermetic contracts only.
+              Plain terminal runs prompt before non-hermetic work. Automation
+              must grant each required capability with a repeatable --allow.
+              Each non-hermetic contract announces its exact capabilities
+              before it starts.
+              Failures print captured stdout/stderr. Successful stdout stays
+              quiet; successful stderr is a warning. The default outer timeout
+              is 180 seconds. Set PANAMA_TEST_TIMEOUT_SECONDS to a positive
+              integer to override it.
+  ${GREEN}contracts${RESET}   Name the contracts that mention a given file, each labeled
+              with manifest capabilities. A heuristic over the text of tests/, so it
+              answers "what should I run" rather than "what covers this".
+  ${GREEN}upgrade${RESET}     Re-run ./install from anywhere, interview and all. For a new
+              machine, or to change an answer you gave. Routine updates are
+              '$PROGRAM update', which asks nothing.
+  ${GREEN}migrate${RESET}     Apply repairs this machine has not had yet. The half of an
+              upgrade that ./install cannot do, because installing only ever
+              adds. Safe to re-run; nothing is applied twice.
  ${GREEN}apps${RESET}        Choose applications to install: pick a category, then tick
              what you want. The same catalog ./install offers, minus the
              install.
  ${GREEN}app${RESET}         Build and install an application that neither dnf nor
              Flathub carries. With no name, lists what is available.
+  ${GREEN}server${RESET}      The compose services a server machine runs: list, enable,
+              disable, status, relink. See 'panama server help'.
  ${GREEN}help${RESET}        Show this help (also -h, --help).

 ${BOLD}Options:${RESET}
@@ -86,13 +119,22 @@ ${BOLD}Options:${RESET}

 ${BOLD}Examples:${RESET}
  $PROGRAM update
+  $PROGRAM update --packages
+  $PROGRAM sync
  $PROGRAM edit
  $PROGRAM doctor --summary
+  $PROGRAM diagnose
+  $PROGRAM diagnose the bar disappears after unplugging the monitor
  $PROGRAM test dock
+  $PROGRAM test --safe
+  $PROGRAM test --allow live-host updates
+  $PROGRAM test --allow live-compositor keybinds
+  PANAMA_TEST_TIMEOUT_SECONDS=300 $PROGRAM test --safe
+  $PROGRAM contracts config/dot/quickshell/services/Displays.qml
  $PROGRAM upgrade
  $PROGRAM apps
  $PROGRAM app
-  $PROGRAM app claude-desktop
+  $PROGRAM app chatgpt-desktop
 EOF
 }

@@ -109,25 +151,116 @@ require_git_repo() {
 # ----------------------------------------------------------------------------
 # Command: update
 # ----------------------------------------------------------------------------
+#
+# The routine command: bring THIS MACHINE up to date. Pull, then hand the rest
+# to `install --upgrade`, which asks nothing.
+#
+# Most of an update needs no stage at all. Every dotfile is a symlink into this
+# checkout, so an edit to an existing config/dot/** file is live the moment the
+# pull returns -- there is nothing to apply. Stages earn their place when a pull
+# brings something structural: a new dotfile directory to link, a file under
+# config/copy/ to place as root, a new package, a gsettings change. Running the
+# cheap ones every time is idempotent and takes seconds; working out which were
+# needed is guesswork with a silent failure mode.
+#
+# Uncommitted work never blocks an update. It is stashed across the pull and
+# restored afterwards -- and if restoring conflicts, the tree is reset rather
+# than left holding conflict markers, because on this repository those markers
+# are not something you fix at your leisure. They are live in ~/.config the
+# instant they are written, and a half-merged .qml is a shell that will not
+# parse.
 cmd_update() {
  require_git_repo
  cd "$PANAMA_DIR"

  info "Panama repo: ${BOLD}${PANAMA_DIR}${RESET}"

-  # Any changes in the working tree? (modified, staged, or untracked)
-  if [[ -z "$(git status --porcelain)" ]]; then
-    info "Working tree is clean — pulling latest changes."
-    if git pull --ff-only; then
-      ok "Already in sync."
+  local stashed=0 conflict_stash=""
+  if [[ -n "$(git status --porcelain)" ]]; then
+    info "Local changes; stashing them across the pull."
+    if git stash push --include-untracked -m "panama-update-$(date +%s)" >/dev/null; then
+      stashed=1
    else
-      err "git pull failed."
+      err "Could not stash local changes, so the pull would overwrite them."
      exit 1
    fi
+  fi
+
+  # --ff-only on purpose. A diverged branch is something to resolve
+  # deliberately, not something an update command should merge on your behalf.
+  # It is a warning rather than an error: the stages below are still worth
+  # running against whatever is checked out.
+  if git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+    info "Pulling..."
+    if git pull --ff-only; then
+      ok "Checkout is current."
+    else
+      warn "Could not fast-forward — continuing with what is checked out."
+    fi
+  else
+    warn "No upstream configured for this branch; nothing to pull."
+  fi
+
+  if (( stashed )); then
+    if git stash pop >/dev/null 2>&1; then
+      ok "Local changes restored."
+    else
+      # A conflicted pop keeps the stash entry -- git says so itself, and the
+      # contract proves it -- so resetting here loses nothing. The work stays
+      # in the stash, where nothing is reading it, instead of in your live
+      # config as merge markers.
+      git reset --hard HEAD >/dev/null 2>&1
+      conflict_stash="$(git stash list --format='%gd: %gs' 2>/dev/null | head -1)"
+      warn "Your local changes conflict with what was pulled; they stay stashed."
+    fi
+  fi
+
+  local installer="$PANAMA_DIR/install"
+  if [[ ! -x "$installer" ]]; then
+    err "The installer is missing from $installer"
+    exit 1
+  fi
+
+  local rc=0
+  "$installer" --upgrade "$@" || rc=$?
+
+  # Repeated at the very end rather than only where it happened. A warning
+  # printed before twenty minutes of dnf output is a warning nobody read.
+  if [[ -n "$conflict_stash" ]]; then
+    echo
+    warn "Your local changes were NOT restored — they conflicted with the pull."
+    printf '  They are safe at %s%s%s\n' "$BOLD" "$conflict_stash" "$RESET"
+    printf '  Restore them with: %sgit stash pop%s\n' "$BOLD" "$RESET"
+  fi
+
+  return $rc
+}
+
+# ----------------------------------------------------------------------------
+# Command: sync
+# ----------------------------------------------------------------------------
+#
+# The other half of what `update` used to mean: commit and push MY EDITS.
+# Panama is a working tree people edit in place -- every dotfile is a symlink
+# into it -- so "I changed something, put it upstream" is a daily action and
+# deserves its own verb rather than sharing one with "update my machine".
+#
+# The commit happens BEFORE anything is fetched, which is why there is no stash
+# in here. By the time upstream is consulted the work is a commit, so a moved
+# upstream is a rebase over committed history -- recoverable, ordinary, and
+# nothing like a stash pop conflicting into a live config.
+cmd_sync() {
+  require_git_repo
+  cd "$PANAMA_DIR"
+
+  info "Panama repo: ${BOLD}${PANAMA_DIR}${RESET}"
+
+  if [[ -z "$(git status --porcelain)" ]]; then
+    ok "Nothing to commit — the working tree is clean."
+    info "To update this machine, run: ${BOLD}${PROGRAM} update${RESET}"
    return
  fi

-  # Show what changed
  header "Changed files"
  git -c color.status=always status --short

@@ -151,7 +284,6 @@ cmd_update() {
    return
  fi

-  # Commit message
  local msg
  printf '%s?%s Commit message: ' "${CYAN}${BOLD}" "$RESET"
  read -r msg || true
@@ -160,46 +292,35 @@ cmd_update() {
    warn "No message given — using: ${BOLD}${msg}${RESET}"
  fi

-  # Is the local branch up to date with its upstream?
-  info "Checking whether the repo is up to date..."
-  if git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
-    git fetch --quiet
-    local local_rev remote_rev base_rev
-    local_rev=$(git rev-parse @)
-    remote_rev=$(git rev-parse '@{u}')
-    base_rev=$(git merge-base @ '@{u}')
-
-    if [[ "$local_rev" == "$remote_rev" ]]; then
-      ok "Repo is up to date."
-    elif [[ "$local_rev" == "$base_rev" ]]; then
-      warn "Repo is behind upstream — stashing, pulling, then re-applying."
-      info "Stashing local changes..."
-      git stash push --include-untracked -m "panama-update-$(date +%s)" >/dev/null
-
-      if ! git pull --ff-only; then
-        err "git pull failed — restoring your changes."
-        git stash pop || true
-        exit 1
-      fi
-
-      info "Re-applying stashed changes..."
-      if ! git stash pop; then
-        err "Conflict while re-applying changes. Resolve it, then commit manually."
-        exit 1
-      fi
-    else
-      warn "Local branch has diverged from upstream — committing locally only."
-    fi
-  else
-    warn "No upstream configured for this branch — committing locally only."
-  fi
-
-  # Commit everything
  info "Committing changes..."
  git add -A
  git commit -m "$msg"
  ok "Committed: ${BOLD}${msg}${RESET}"

+  if ! git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+    warn "No upstream configured for this branch — committed locally only."
+    return
+  fi
+
+  # Only now, with the work safely committed, is it worth looking upstream.
+  info "Checking whether upstream has moved..."
+  git fetch --quiet
+  local remote_rev base_rev
+  remote_rev=$(git rev-parse '@{u}')
+  base_rev=$(git merge-base @ '@{u}')
+
+  if [[ "$base_rev" != "$remote_rev" ]]; then
+    warn "Upstream has moved — rebasing your commit onto it."
+    if ! git pull --rebase; then
+      err "The rebase stopped on a conflict."
+      err "Resolve it, then: git rebase --continue"
+      exit 1
+    fi
+    ok "Rebased onto upstream."
+  else
+    ok "Upstream has not moved."
+  fi
+
  echo
  if confirm "Push the changes now?"; then
    info "Pushing..."
@@ -244,63 +365,551 @@ cmd_doctor() {
  exec "$doctor" "$@"
 }

+# ----------------------------------------------------------------------------
+# Command: diagnose
+# ----------------------------------------------------------------------------
+#
+# The by-hand rung of the escalation ladder. Every other rung starts from an
+# event -- a crash, a failed reload, a red check -- and this one starts from a
+# person who can tell that something is wrong but not what.
+#
+# It gathers the two things anybody would be asked for first anyway (what the
+# health check says, what the journal has been complaining about) and whatever
+# words follow the command, then hands the lot to the configured agent. The free
+# text is the valuable part: "the bar disappears after unplugging the monitor"
+# is a symptom no collector reports, and it is the difference between an agent
+# reading a health summary and an agent looking for something.
+cmd_diagnose() {
+  local launcher="$PANAMA_DIR/bin/panama-agent"
+  if [[ ! -x "$launcher" ]]; then
+    err "The agent launcher is missing from $launcher"
+    exit 1
+  fi
+
+  local complaint="$*"
+
+  local health="(the health check did not run)"
+  local doctor="$PANAMA_DIR/config/dot/quickshell/scripts/panama-doctor"
+  if [[ -x "$doctor" ]]; then
+    health="$("$doctor" --summary 2>&1)" || true
+  fi
+
+  # Bounded twice, and not out of tidiness. journalctl counts entries, not
+  # lines, and thirty entries on this machine came to 2,430 lines and a quarter
+  # of a megabyte -- one multi-line traceback each. The prompt leaves as a
+  # single argv element, which the kernel caps at 128KB, so an unbounded excerpt
+  # turns this command into "Argument list too long" rather than a diagnosis.
+  local errors="(nothing at error level in this boot's user journal)"
+  if command -v journalctl >/dev/null 2>&1; then
+    local recent
+    recent="$(journalctl --user -b -p err -n 30 --no-pager --output=short 2>/dev/null \
+      | cut -c 1-300 | tail -80)" || true
+    [[ -n "${recent// }" ]] && errors="$recent"
+  fi
+
+  local complaint_section="Nothing in particular was reported; this was run to look around."
+  [[ -n "${complaint// }" ]] && complaint_section="$complaint"
+
+  local prompt
+  prompt="$(cat <<PROMPT
+Something is wrong with this Panama machine and I would like to know what.
+
+What I noticed:
+
+$complaint_section
+
+What panama doctor --summary says:
+
+$health
+
+The last error-level lines in this boot's user journal:
+
+$errors
+
+Panama is checked out at $PANAMA_DIR and every dotfile in ~/.config is a symlink
+into it, so anything you find is a tracked file here rather than a copy. Start
+by reading: work out what is actually broken and say so before changing
+anything. If a check is red, 'panama doctor' with no arguments has the long form
+of it. Root work goes through panama-sudo, which shows me your reason.
+PROMPT
+)"
+
+  # exec: from here on the agent's terminal is the process, and this shell has
+  # nothing left to do that the agent is not doing better.
+  exec "$launcher" --prompt "$prompt"
+}
+
+# ----------------------------------------------------------------------------
+# Contract manifest
+# ----------------------------------------------------------------------------
+#
+# The manifest is the runtime authority for every collected contract. An absent
+# manifest is unsafe: this command must never infer that unclassified tests are
+# hermetic.
+CONTRACT_MANIFEST="tests/contracts.manifest"
+CONTRACT_CAPABILITIES=(hermetic live-host live-compositor live-desktop network privileged)
+
+contract_paths() {
+  local candidate
+  while IFS= read -r candidate; do
+    [[ -x "$candidate" || "$candidate" == *_test.py ]] || continue
+    printf 'tests/%s\n' "${candidate#"$PANAMA_DIR/tests/"}"
+  done < <(find "$PANAMA_DIR/tests" -type f \
+    -not -path '*/fixtures/*' -not -path '*__pycache__*' | sort)
+}
+
+contract_manifest_entries() {
+  local line capabilities path
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
+    IFS=$' \t' read -r capabilities path <<<"$line"
+    printf '%s\t%s\n' "$path" "$capabilities"
+  done < "$PANAMA_DIR/$CONTRACT_MANIFEST"
+}
+
+require_contract_manifest() {
+  [[ -r "$PANAMA_DIR/$CONTRACT_MANIFEST" ]] || {
+    err "Contract manifest is missing or unreadable: $PANAMA_DIR/$CONTRACT_MANIFEST"
+    return 1
+  }
+}
+
+validate_contract_manifest() {
+  require_contract_manifest || return 1
+
+  local manifest="$PANAMA_DIR/$CONTRACT_MANIFEST"
+  local line capabilities path extra previous_comment="" previous_was_comment=0
+  local previous_path="" capability discovered
+  local -a capability_list=() findings=()
+  local -A expected_contracts=() manifest_paths=()
+
+  while IFS= read -r discovered; do
+    expected_contracts["$discovered"]=1
+  done < <(contract_paths)
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if [[ "$line" =~ ^[[:space:]]*# ]]; then
+      previous_comment="${line#*#}"
+      previous_comment="${previous_comment#"${previous_comment%%[![:space:]]*}"}"
+      previous_comment="${previous_comment%"${previous_comment##*[![:space:]]}"}"
+      previous_was_comment=1
+      continue
+    fi
+
+    if [[ "$line" =~ ^[[:space:]]*$ ]]; then
+      previous_comment=""
+      previous_was_comment=0
+      continue
+    fi
+
+    IFS=$' \t' read -r capabilities path extra <<<"$line"
+    if [[ -z "${capabilities:-}" || -z "${path:-}" || -n "${extra:-}" ]]; then
+      findings+=("manifest line is not exactly two fields: $line")
+      previous_comment=""
+      previous_was_comment=0
+      continue
+    fi
+
+    if [[ -n "$previous_path" && "$path" < "$previous_path" ]]; then
+      findings+=('paths are not lexicographically sorted')
+    fi
+    previous_path="$path"
+
+    if [[ -n "${manifest_paths[$path]:-}" ]]; then
+      findings+=("duplicate path $path")
+    fi
+    manifest_paths["$path"]=1
+
+    local -A line_capabilities=()
+    if [[ "$capabilities" == ,* || "$capabilities" == *, || "$capabilities" == *,,* ]]; then
+      findings+=("empty capability on $path")
+    fi
+    IFS=',' read -r -a capability_list <<<"$capabilities"
+    for capability in "${capability_list[@]}"; do
+      [[ -n "$capability" ]] || continue
+      if [[ -n "${line_capabilities[$capability]:-}" ]]; then
+        findings+=("duplicate capability $capability on $path")
+      fi
+      line_capabilities["$capability"]=1
+      is_contract_capability "$capability" \
+        || findings+=("unknown capability $capability on $path")
+    done
+
+    if [[ -n "${line_capabilities[hermetic]:-}" && ${#line_capabilities[@]} -ne 1 ]]; then
+      findings+=("hermetic must appear alone on $path")
+    fi
+
+    if [[ "$capabilities" != hermetic ]]; then
+      if (( previous_was_comment != 1 )); then
+        findings+=("$path is non-hermetic but lacks a directly preceding comment")
+      elif [[ -z "$previous_comment" ]]; then
+        findings+=("$path is non-hermetic but lacks a non-empty directly preceding comment")
+      fi
+    fi
+    previous_comment=""
+    previous_was_comment=0
+  done < "$manifest"
+
+  for discovered in "${!expected_contracts[@]}"; do
+    [[ -n "${manifest_paths[$discovered]:-}" ]] \
+      || findings+=("missing contract $discovered")
+  done
+  for path in "${!manifest_paths[@]}"; do
+    [[ -n "${expected_contracts[$path]:-}" ]] \
+      || findings+=("stale manifest path $path")
+  done
+
+  if (( ${#findings[@]} > 0 )); then
+    err "Contract manifest validation failed with ${#findings[@]} finding(s):"
+    printf '  - %s\n' "${findings[@]}" >&2
+    return 1
+  fi
+}
+
+test_usage() {
+  err "Usage: ${BOLD}$PROGRAM test [--safe] [--allow <capability>] [pattern]${RESET}"
+  return 2
+}
+
+is_contract_capability() {
+  local capability="$1" known
+  for known in "${CONTRACT_CAPABILITIES[@]}"; do
+    [[ "$capability" == "$known" ]] && return 0
+  done
+  return 1
+}
+
 # ----------------------------------------------------------------------------
 # Command: test
 # ----------------------------------------------------------------------------
 #
-# The contracts are the main safety net in this repository and had no entry
-# point: 121 executables with no runner and no mention in the README, which is
-# most of the way to not having them.
+# The contracts are the main safety net in this repository. The manifest is the
+# single list of what the runner executes and which external boundaries each
+# contract reaches.
 #
 # Each runs in its own process and a failure does not stop the rest, because the
 # useful output is the whole list of what is broken rather than the first thing
 # that broke. The exit code is what a caller can act on.
-cmd_test() {
-  local pattern="${1:-}"
-  local -a suite=()
+#
+# --safe runs only contracts the manifest classifies as hermetic and reports
+# each external capability it skipped. A plain terminal run asks before any
+# selected non-hermetic work. Automation must grant every required capability
+# with repeatable --allow flags. Non-hermetic contracts announce their exact
+# capability list before execution. Each contract gets an outer timeout, 180
+# seconds by default. PANAMA_TEST_TIMEOUT_SECONDS accepts a positive integer
+# override. Failures include captured stdout and stderr. Successful stdout
+# stays quiet, while successful stderr is surfaced as a warning.
+PANAMA_ACTIVE_CONTRACT_PID=""
+PANAMA_CONTRACT_CAPTURE_DIR=""

-  # Executables, plus the Python suites. Those are unittest files rather than
-  # executables, and collecting only what has the executable bit would skip them
-  # without saying so -- which is how all three came to be run by nothing at all.
-  # A runner with a blind spot is worse than no runner, because it reports PASS.
-  while IFS= read -r path; do
-    [[ -x "$path" || "$path" == *_test.py ]] || continue
-    [[ -z "$pattern" || "$path" == *"$pattern"* ]] && suite+=("$path")
-  done < <(find "$PANAMA_DIR/tests" -type f -not -path '*/fixtures/*' -not -path '*__pycache__*' | sort)
+cleanup_contract_capture() {
+  if [[ -n "$PANAMA_CONTRACT_CAPTURE_DIR" && -d "$PANAMA_CONTRACT_CAPTURE_DIR" ]]; then
+    rm -rf -- "$PANAMA_CONTRACT_CAPTURE_DIR" || true
+  fi
+  PANAMA_CONTRACT_CAPTURE_DIR=""
+}

-  if (( ${#suite[@]} == 0 )); then
-    err "No contracts match '${pattern}'"
-    exit 1
+terminate_active_contract() {
+  local pid="$PANAMA_ACTIVE_CONTRACT_PID"
+  PANAMA_ACTIVE_CONTRACT_PID=""
+  [[ "$pid" =~ ^[1-9][0-9]*$ && "$pid" != "$$" ]] || return 0
+
+  # GNU timeout owns a process group whose ID is its PID. Signal that complete
+  # group so a contract cannot leave descendants behind, with a direct-PID
+  # fallback for implementations that do not create the group.
+  kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+  wait "$pid" 2>/dev/null || true
+}
+
+handle_contract_signal() {
+  local signal_status="$1"
+  trap - INT TERM
+  terminate_active_contract
+  cleanup_contract_capture
+  trap - EXIT
+  exit "$signal_status"
+}
+
+prepare_contract_capture() {
+  local capture_dir=""
+  if ! capture_dir="$(mktemp -d)"; then
+    err 'Could not create contract capture directory.'
+    return 1
+  fi
+  if [[ -z "$capture_dir" || ! -d "$capture_dir" ]]; then
+    err 'Could not create contract capture directory.'
+    return 1
  fi

+  PANAMA_CONTRACT_CAPTURE_DIR="$capture_dir"
+  trap cleanup_contract_capture EXIT
+  trap 'handle_contract_signal 130' INT
+  trap 'handle_contract_signal 143' TERM
+}
+
+cmd_test() {
+  local timeout_seconds="${PANAMA_TEST_TIMEOUT_SECONDS:-180}"
+  [[ "$timeout_seconds" =~ ^[1-9][0-9]*$ ]] || {
+    err 'PANAMA_TEST_TIMEOUT_SECONDS must be a positive integer.'
+    return 2
+  }
+
+  validate_contract_manifest || return 1
+  cmd_test_impl "$timeout_seconds" "$@"
+}
+
+cmd_test_impl() {
+  local timeout_seconds="$1"
+  shift
+  local pattern="" safe=0 arg capability capabilities rel path
+  local -A grants=() manifest_capabilities=() skipped_counts=() missing_grants=() selected_capabilities=()
+  local -a suite=() missing_capability_list=() selected_capability_list=() capability_list=()
+
+  # Position-independent: flags can precede or follow the optional pattern.
+  while (( $# > 0 )); do
+    arg="$1"
+    shift
+    case "$arg" in
+      --safe) safe=1 ;;
+      --allow)
+        (( $# > 0 )) || { test_usage; return 2; }
+        capability="$1"
+        shift
+        is_contract_capability "$capability" || {
+          err "Unknown contract capability: $capability"
+          return 2
+        }
+        [[ "$capability" != hermetic ]] || {
+          err 'hermetic contracts do not need --allow.'
+          return 2
+        }
+        grants["$capability"]=1
+        ;;
+      --*) test_usage; return 2 ;;
+      *)
+        [[ -z "$pattern" ]] || { test_usage; return 2; }
+        pattern="$arg"
+        ;;
+    esac
+  done
+
+  (( safe == 0 || ${#grants[@]} == 0 )) || {
+    err '--safe cannot be combined with --allow.'
+    return 2
+  }
+
+  while IFS=$'\t' read -r rel capabilities; do
+    manifest_capabilities["$rel"]="$capabilities"
+    [[ -z "$pattern" || "$rel" == *"$pattern"* ]] || continue
+    if (( safe )) && [[ "$capabilities" != hermetic ]]; then
+      IFS=',' read -r -a capability_list <<<"$capabilities"
+      for capability in "${capability_list[@]}"; do
+        (( ++skipped_counts["$capability"] ))
+      done
+      continue
+    fi
+    suite+=("$rel")
+  done < <(contract_manifest_entries)
+
+  if (( ${#suite[@]} == 0 )); then
+    if (( safe )) && (( ${#skipped_counts[@]} > 0 )); then
+      err "Every contract matching '${pattern}' needs an external capability; --safe skipped all of them."
+    else
+      err "No contracts match '${pattern}'"
+    fi
+    return 1
+  fi
+
+  if (( safe )); then
+    for capability in "${CONTRACT_CAPABILITIES[@]}"; do
+      [[ "$capability" == hermetic ]] && continue
+      printf 'Skipped %d %s contract(s).\n' "${skipped_counts[$capability]:-0}" "$capability"
+    done
+  else
+    for rel in "${suite[@]}"; do
+      capabilities="${manifest_capabilities[$rel]}"
+      [[ "$capabilities" == hermetic ]] && continue
+      IFS=',' read -r -a capability_list <<<"$capabilities"
+      for capability in "${capability_list[@]}"; do
+        selected_capabilities["$capability"]=1
+        [[ -n "${grants[$capability]:-}" ]] || missing_grants["$capability"]=1
+      done
+    done
+    for capability in "${CONTRACT_CAPABILITIES[@]}"; do
+      [[ "$capability" == hermetic ]] && continue
+      [[ -n "${selected_capabilities[$capability]:-}" ]] && selected_capability_list+=("$capability")
+      [[ -n "${missing_grants[$capability]:-}" ]] && missing_capability_list+=("$capability")
+    done
+    if (( ${#missing_capability_list[@]} > 0 )); then
+      if [[ -t 0 && -t 2 ]]; then
+        confirm "Run ${#suite[@]} contract(s) requiring: ${selected_capability_list[*]}?" || {
+          warn 'No contracts were run.'
+          return 1
+        }
+      else
+        err "Selected contracts require: ${missing_capability_list[*]}."
+        for capability in "${missing_capability_list[@]}"; do
+          printf '  Automation: pass --allow %s\n' "$capability" >&2
+        done
+        return 1
+      fi
+    fi
+  fi
+
+  local capture_dir stdout_file stderr_file name run_status index=0 final_status=0
+  local -a failed=() runner=()
+  prepare_contract_capture || return 1
+  capture_dir="$PANAMA_CONTRACT_CAPTURE_DIR"
+
  info "Running ${#suite[@]} contract(s)"
-  local -a failed=()
-  local path name
-  local -a runner
-  for path in "${suite[@]}"; do
-    name="${path#"$PANAMA_DIR"/tests/}"
+  for index in "${!suite[@]}"; do
+    rel="${suite[$index]}"
+    path="$PANAMA_DIR/$rel"
+    name="${rel#tests/}"
+    stdout_file="$capture_dir/$index.stdout"
+    stderr_file="$capture_dir/$index.stderr"
    if [[ "$path" == *_test.py ]]; then
      runner=(python3 "$path")
    else
      runner=("$path")
    fi
-    if "${runner[@]}" >/dev/null 2>&1; then
-      ok "$name"
-    else
-      err "$name"
-      failed+=("$name")
+    capabilities="${manifest_capabilities[$rel]}"
+    if [[ "$capabilities" != hermetic ]]; then
+      info "Running $name [$capabilities]"
    fi
+    run_status=0
+    timeout --signal=TERM --kill-after=5 "$timeout_seconds" \
+      "${runner[@]}" >"$stdout_file" 2>"$stderr_file" &
+    PANAMA_ACTIVE_CONTRACT_PID=$!
+    wait "$PANAMA_ACTIVE_CONTRACT_PID" || run_status=$?
+    PANAMA_ACTIVE_CONTRACT_PID=""
+    if (( run_status == 0 )); then
+      ok "$name"
+      if [[ -s "$stderr_file" ]]; then
+        warn "$name wrote to stderr:"
+        cat "$stderr_file" >&2
+      fi
+      continue
+    fi
+
+    if (( run_status == 124 || run_status == 137 )); then
+      err "$name timed out after ${timeout_seconds}s"
+    else
+      err "$name failed (exit $run_status)"
+    fi
+    [[ -s "$stdout_file" ]] && {
+      printf '%s stdout:\n' "$name" >&2
+      cat "$stdout_file" >&2
+    }
+    [[ -s "$stderr_file" ]] && {
+      printf '%s stderr:\n' "$name" >&2
+      cat "$stderr_file" >&2
+    }
+    failed+=("$name")
  done

  header "Result"
  if (( ${#failed[@]} == 0 )); then
    ok "${#suite[@]} contract(s) passed"
-    return 0
-  fi
+  else
    err "${#failed[@]} of ${#suite[@]} failed:"
    printf '    %s\n' "${failed[@]}" >&2
-  warn "Run one on its own to see why: ${BOLD}${PANAMA_DIR}/tests/<name>${RESET}"
+    final_status=1
+  fi
+
+  cleanup_contract_capture
+  trap - EXIT INT TERM
+  return "$final_status"
+}
+
+# ----------------------------------------------------------------------------
+# Command: contracts
+# ----------------------------------------------------------------------------
+#
+# "I changed this file -- what should I run?" The suite is large enough that
+# running all of it or guessing from contract names are both poor answers.
+#
+# This is a grep, and says so. A contract that names the file, or a
+# parent-trimmed suffix of it, or just its basename, is a contract worth
+# running; one that reaches the file through a harness or a generated artifact
+# is not found, which is why the empty answer says "coverage may be indirect"
+# rather than "nothing covers this". Naming a file the suite does not mention is
+# a real answer -- exit 1 so a script can tell the difference -- but it is a
+# statement about this search, not about the file.
+#
+# Each hit is labeled from tests/contracts.manifest, so the output also answers
+# which boundary the matching contract reaches.
+cmd_contracts() {
+  local target="${1:-}"
+  if [[ -z "$target" ]]; then
+    err "Which file? Usage: ${BOLD}$PROGRAM contracts <file>${RESET}"
+    exit 1
+  fi
+
+  # Absolute, relative to where you are standing, or repo-relative -- all three
+  # are how somebody refers to a file in this tree, and readlink resolves the
+  # symlinked dotfile in ~/.config back into the checkout it points at.
+  local absolute=""
+  if [[ -e "$target" ]]; then
+    absolute="$(readlink -f "$target")"
+  elif [[ -e "$PANAMA_DIR/$target" ]]; then
+    absolute="$(readlink -f "$PANAMA_DIR/$target")"
+  else
+    err "No such file: '$target'"
+    printf 'Give a path, absolute or relative to here or to %s.\n' "$PANAMA_DIR" >&2
+    exit 1
+  fi
+
+  local path
+  case "$absolute" in
+    "$PANAMA_DIR"/*) path="${absolute#"$PANAMA_DIR"/}" ;;
+    *)
+      err "'$target' is outside the Panama repo (${PANAMA_DIR})."
+      exit 1
+      ;;
+  esac
+
+  # The repo-relative path, then each parent trimmed off in turn, ending at the
+  # basename. Contracts refer to their subject every one of these ways: by the
+  # full path from the repo root, by the path from the shell directory, and by
+  # name alone.
+  local -a patterns=()
+  local suffix="$path"
+  while :; do
+    patterns+=(-e "$suffix")
+    [[ "$suffix" == */* ]] || break
+    suffix="${suffix#*/}"
+  done
+
+  validate_contract_manifest || return 1
+  local -A manifest_capabilities=()
+  local capabilities
+  while IFS=$'\t' read -r rel capabilities; do
+    manifest_capabilities["$rel"]="$capabilities"
+  done < <(contract_manifest_entries)
+
+  # The same collection `test` runs, so anything named here is something the
+  # runner would actually execute.
+  local -a hits=()
+  local candidate rel
+  while IFS= read -r rel; do
+    candidate="$PANAMA_DIR/$rel"
+    grep -qF "${patterns[@]}" "$candidate" 2>/dev/null || continue
+    hits+=("$rel")
+  done < <(contract_paths)
+
+  if (( ${#hits[@]} == 0 )); then
+    printf 'No contract mentions %s — coverage may be indirect (a harness or a generated artifact); nothing verified.\n' "$path" >&2
+    exit 1
+  fi
+
+  for rel in "${hits[@]}"; do
+    [[ -n "${manifest_capabilities[$rel]:-}" ]] || {
+      err "Contract has no manifest capability label: $rel"
      return 1
+    }
+    printf '%s  [%s]\n' "$rel" "${manifest_capabilities[$rel]}"
+  done
 }

 # ----------------------------------------------------------------------------
@@ -321,6 +930,24 @@ cmd_upgrade() {
  exec "$installer" "$@"
 }

+# ----------------------------------------------------------------------------
+# Command: migrate
+# ----------------------------------------------------------------------------
+#
+# What ./install cannot do. The installer only ever adds -- it copies over /,
+# links dotfiles, installs packages -- so a machine set up months ago keeps
+# whatever this repository has since decided was wrong. Migrations are the one
+# mechanism that can remove a file, disable a unit, or repair a symlink on a
+# machine that already exists. See bin/panama-migrate.
+cmd_migrate() {
+  local runner="$PANAMA_DIR/bin/panama-migrate"
+  if [[ ! -x "$runner" ]]; then
+    err "The migration runner is missing from $runner"
+    exit 1
+  fi
+  exec "$runner" "$@"
+}
+
 # ----------------------------------------------------------------------------
 # Command: app
 # ----------------------------------------------------------------------------
@@ -518,12 +1145,17 @@ main() {
  local cmd="${1:-}"
  case "$cmd" in
    update)        shift; cmd_update "$@" ;;
+    sync)          shift; cmd_sync "$@" ;;
    edit)          shift; cmd_edit "$@" ;;
    doctor)        shift; cmd_doctor "$@" ;;
+    diagnose)      shift; cmd_diagnose "$@" ;;
    test)          shift; cmd_test "$@" ;;
+    contracts)     shift; cmd_contracts "$@" ;;
    upgrade)       shift; cmd_upgrade "$@" ;;
+    migrate)       shift; cmd_migrate "$@" ;;
    app)           shift; cmd_app "$@" ;;
    apps)          shift; cmd_apps "$@" ;;
+    server)        shift; exec "$PANAMA_DIR/bin/panama-server" "$@" ;;
    help|-h|--help|"") usage ;;
    --version)     printf '%s %s\n' "$PROGRAM" "$VERSION" ;;
    *)
@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+
+# Hand a prompt to whichever coding agent this machine has chosen.
+#
+# Every rung of the escalation ladder ends here: a crash toast, a failed shell
+# reload, a red health check, `panama diagnose`. They gather facts; this decides
+# which binary runs them and puts it in a terminal you can watch and interrupt.
+#
+# Two settings decide everything, and both are read at press time rather than at
+# start time, so choosing an agent in Settings takes effect on the next crash
+# without restarting anything:
+#
+#   preferredAgent    none | claude | codex   ("none" is the default: silence)
+#   agentAutoApprove  true -> the agent starts in its own "don't stop to ask"
+#                     mode; false -> its normal prompting mode, untouched.
+#
+# "none" exits 0 without a word. It is not an error to have no agent; it is the
+# shipped state, and a rung that shouted about it would be a rung that gets
+# turned off.
+#
+#   panama-agent                     open the agent on the repo
+#   panama-agent --prompt "text"     open it with something to work on
+#
+# Environment seams, for the contract and for a second checkout:
+#
+#   PANAMA_PATH             the repository; also the agent's working directory
+#   PANAMA_AGENT_SETTINGS   the settings file to read (default: the real one)
+#
+# ---------------------------------------------------------------------------
+# Adapted from Omarchy's bin/omarchy-agent (https://github.com/basecamp/omarchy)
+#
+# Copyright (c) David Heinemeier Hansson
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
+SETTINGS="${PANAMA_AGENT_SETTINGS:-${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json}"
+
+# A fixed window class rather than the per-binary default, so one Hyprland rule
+# can catch every agent window regardless of which agent is chosen.
+readonly WINDOW_CLASS="panama-agent"
+
+# THE INHERITED PATH IS NOT THE USER'S PATH. Every rung except `panama diagnose`
+# reaches this script from the Quickshell shell, which systemd starts with
+# neither PANAMA_PATH nor ~/.local/bin -- and ~/.local/bin is where both agents
+# install themselves. Trusting PATH here meant a perfectly well installed agent
+# reporting itself as missing, into the stderr of a detached process nobody will
+# ever read: the whole ladder failing silently, which is the exact failure it
+# exists to prevent.
+#
+# So the binary is resolved rather than named. PATH first, because a user who
+# put an agent somewhere else meant it; then the XDG user bin directory, which
+# is where the installers actually put them.
+resolve_agent() {
+    local name="$1" found
+    found="$(command -v "$name" 2>/dev/null)" && { printf '%s' "$found"; return 0; }
+    [[ -x "$HOME/.local/bin/$name" ]] && { printf '%s' "$HOME/.local/bin/$name"; return 0; }
+    return 1
+}
+
+# The same repair, for the agent's own sake rather than this script's: an agent
+# launched from a notification click would otherwise run every shell command it
+# is asked to with a PATH unlike the one the user gets in a terminal. Applied
+# just before the spawn rather than here, so resolve_agent above is answering
+# the question the caller actually asked -- "can this be found from where I was
+# started" -- instead of one this script has already fixed for itself.
+repair_path() {
+    case ":$PATH:" in
+        *":$HOME/.local/bin:"*) ;;
+        *) PATH="$PATH:$HOME/.local/bin" ;;
+    esac
+    export PATH
+}
+
+usage() {
+    cat <<'EOF'
+Usage: panama-agent [--prompt "text"]
+
+Opens the agent named by preferredAgent in a terminal, in the Panama checkout.
+With no agent chosen, exits silently: choose one on Settings > System > Agents.
+EOF
+}
+
+prompt=""
+while (($#)); do
+    case "$1" in
+        --prompt)
+            prompt="${2:?--prompt needs a value}"
+            shift 2
+            ;;
+        -h | --help)
+            usage
+            exit 0
+            ;;
+        *)
+            printf 'panama-agent: unexpected argument: %s\n' "$1" >&2
+            usage >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Same shape as panama-idle's reader: a missing file, a missing key and an
+# explicit null all mean "the default", because all three describe a machine
+# that has never been asked the question.
+read_setting() {
+    local key="$1" fallback="$2"
+    [[ -r "$SETTINGS" ]] || { printf '%s' "$fallback"; return; }
+    command -v jq >/dev/null 2>&1 || { printf '%s' "$fallback"; return; }
+    jq -r --arg k "$key" --arg d "$fallback" \
+        'if has($k) and (.[$k] != null) then (.[$k] | tostring) else $d end' \
+        "$SETTINGS" 2>/dev/null || printf '%s' "$fallback"
+}
+
+agent="$(read_setting preferredAgent none)"
+
+# The shipped state. Nothing to launch, nothing to say.
+[[ -n "$agent" && "$agent" != "none" ]] || exit 0
+
+auto_approve="$(read_setting agentAutoApprove true)"
+
+case "$agent" in
+    claude | codex) ;;
+    *)
+        printf 'panama-agent: unsupported preferredAgent: %s\n' "$agent" >&2
+        printf 'Choose one on Settings > System > Agents.\n' >&2
+        exit 1
+        ;;
+esac
+
+# Resolved to a path before argv is built, so kitty is never asked to repeat a
+# PATH lookup this script has already done more carefully than kitty could.
+if ! agent_bin="$(resolve_agent "$agent")"; then
+    printf 'panama-agent: %s is not installed.\n' "$agent" >&2
+    printf 'Looked on PATH and in %s.\n' "$HOME/.local/bin" >&2
+    printf 'Install it, or choose another agent on Settings > System > Agents.\n' >&2
+    exit 1
+fi
+
+# The per-agent launch table. VERIFIED against the installed binaries' --help on
+# 2026-08-25 (claude 2.1.245, codex-cli 0.149.1) -- these flags are not the same
+# from release to release, so re-run --help before changing them.
+#
+#   claude --permission-mode auto     "auto" is one of acceptEdits/auto/
+#                                     bypassPermissions/manual/dontAsk/plan
+#   codex  --approve-for-me           routes approvals through automatic review
+#                                     inside the workspace-write sandbox
+#
+# With agentAutoApprove off, no mode flag is passed at all: the agent's own
+# configured default is a choice the user already made, and overriding it with
+# an explicit "prompt me" would be this script having an opinion it was told not
+# to have.
+declare -a argv=("$agent_bin")
+case "$agent" in
+    claude) [[ "$auto_approve" == "true" ]] && argv+=(--permission-mode auto) ;;
+    codex) [[ "$auto_approve" == "true" ]] && argv+=(--approve-for-me) ;;
+esac
+
+# One argv element, after the option terminator. Both CLIs take the prompt as a
+# trailing positional, and `--` is what stops a prompt beginning with a dash --
+# or one that happens to read like a subcommand -- from being parsed as flags.
+[[ -n "$prompt" ]] && argv+=(-- "$prompt")
+
+# The checkout, not $HOME: the skills the prompts point at, the repository the
+# agent is being asked about, and .claude/settings.json's pre-approved read-only
+# diagnostics all live here. An agent started anywhere else finds none of them.
+cd "$PANAMA_PATH"
+
+repair_path
+
+# setsid so the agent outlives whatever spawned it -- a notification handler, a
+# crash watcher, a terminal that is about to close.
+exec setsid kitty \
+    --directory "$PANAMA_PATH" \
+    --class "$WINDOW_CLASS" \
+    -e "${argv[@]}"
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+
+# "Something crashed" -> an agent already reading the core dump.
+#
+# Reached by clicking the crash notification panama-crash-watch sends, or run by
+# hand against any PID in `coredumpctl list`. It gathers the four facts
+# systemd-coredump recorded and points at the skill that says what to do with
+# them; the method lives in the skill so it is edited in one place and works
+# whichever agent is configured.
+#
+#   panama-agent-crash <pid> [comm] [exe] [signal]
+#
+# The skill is named AND given as an absolute path. A harness with a skill
+# mechanism follows the name; one without still has a file to read. That is the
+# whole reason this ladder works for more than one agent.
+#
+# ---------------------------------------------------------------------------
+# Adapted from Omarchy's bin/omarchy-agent-crash
+# (https://github.com/basecamp/omarchy)
+#
+# Copyright (c) David Heinemeier Hansson
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
+
+pid="${1:-}"
+if [[ ! "$pid" =~ ^[0-9]+$ ]]; then
+    printf 'Not a PID: %s\n' "${pid:-<missing>}" >&2
+    printf 'Usage: panama-agent-crash <pid> [comm] [exe] [signal]   (see: coredumpctl list)\n' >&2
+    exit 1
+fi
+
+comm="${2:-unknown}"
+exe="${3:-unknown}"
+signal="${4:-unknown}"
+
+skill="$PANAMA_PATH/skills/diagnose-crash/SKILL.md"
+
+# Looked up live so a PID typed by hand still gets a timestamp. A core that has
+# already been rotated away costs only the timestamp, so this is allowed to
+# fail: the other four facts are enough to start on.
+when="$(coredumpctl list "$pid" --no-pager --no-legend 2>/dev/null | tail -1 | cut -d' ' -f1-4)" || true
+when="${when:-unknown}"
+[[ -n "${when// }" ]] || when="unknown"
+
+prompt="$(
+    cat <<PROMPT
+A process crashed on this Panama machine and I want to know why.
+
+What systemd-coredump recorded:
+  process:  $comm
+  PID:      $pid
+  binary:   $exe
+  signal:   $signal
+  time:     $when
+
+Use the diagnose-crash skill. It covers how to investigate, what to rule out
+first, and what to report. If your harness has no skill mechanism, read the
+skill file directly and follow it instead:
+
+  $skill
+PROMPT
+)"
+
+exec "$PANAMA_PATH/bin/panama-agent" --prompt "$prompt"
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+
+# "The shell would not reload" -> an agent already holding the error.
+#
+# Quickshell keeps the old shell running when a reload fails, which is what
+# makes this rung possible at all: the desktop that just refused the new code is
+# still there to notify you about it, and still there to click. shell.qml's
+# onReloadFailed sends that notification; this builds the prompt behind it.
+#
+#   panama-agent-reload "<what Quickshell said>"
+#
+# The failure string on its own is usually one line naming one file. The journal
+# around it is where the rest is -- the QML warnings that preceded the fatal
+# one, the property that was already undefined two saves ago -- so both go in.
+#
+# Environment seams, for the contract:
+#
+#   PANAMA_PATH               the repository
+#   PANAMA_RELOAD_UNIT        the unit to read (default panama-quickshell.service)
+
+set -euo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
+UNIT="${PANAMA_RELOAD_UNIT:-panama-quickshell.service}"
+
+summary="${1:-}"
+if [[ -z "${summary// }" ]]; then
+    printf 'Usage: panama-agent-reload "<the reload failure>"\n' >&2
+    exit 1
+fi
+
+# Read a generous window and filter it down, rather than asking journalctl for
+# forty lines and hoping they were the relevant ones. A failed reload usually
+# arrives after a burst of unrelated shell chatter.
+#
+# Each line is truncated because the prompt leaves as one argv element and the
+# kernel caps that at 128KB; a single Quickshell backtrace can be most of it.
+context=""
+if command -v journalctl >/dev/null 2>&1; then
+    context="$(journalctl --user -u "$UNIT" -n 400 --no-pager --output=cat 2>/dev/null \
+        | grep -iE 'quickshell|\.qml|qml:|panama' \
+        | tail -40 \
+        | cut -c 1-300)" || true
+fi
+[[ -n "${context// }" ]] || context="(nothing in the journal for $UNIT)"
+
+prompt="$(
+    cat <<PROMPT
+The Panama shell refused to reload on this machine. The old shell is still
+running, so the desktop is up, but the change that was just saved is not live.
+
+What Quickshell reported:
+
+$summary
+
+The last relevant lines from $UNIT:
+
+$context
+
+The shell lives in config/dot/quickshell in this repository, symlinked into
+~/.config/quickshell -- so the file that failed to parse is a tracked file here,
+not a copy. Find what broke the reload and say what it is. Read before you
+write: a bad guess saved into this tree is live in the desktop immediately.
+PROMPT
+)"
+
+exec "$PANAMA_PATH/bin/panama-agent" --prompt "$prompt"
@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+
+# Tell somebody when a program crashes.
+#
+# On GNOME, ABRT says so. Under a hand-assembled Hyprland desktop nothing does,
+# and applications die silently -- which is most of how "Linux is flaky" gets
+# earned. Fedora ships systemd-coredump by default, so the information is
+# already there; nobody is reading it.
+#
+# Follows the journal for systemd-coredump's own message id and reports each
+# program once per session.
+#
+# ONCE PER SESSION IS THE WHOLE DESIGN. This machine's portal backend crashes
+# between eleven and sixty times a day -- see the portal-stability check in
+# panama-doctor -- and a notification per crash would be a notification every
+# few minutes for something the user can do nothing about. The first one is
+# news; the fortieth is why people turn notifications off. The health page
+# carries the running count for anyone who wants it.
+#
+# When an agent has been chosen, the notification stops being a dead end. It
+# carries the diagnosis command as data in a `panama-exec` hint, which the shell
+# runs on click. Command-as-data rather than a libnotify action, because an
+# action would tie the click to this process still being alive to hear it, and
+# this process is a `journalctl -f` that outlives nothing in particular. The
+# hint survives a shell restart and never blocks the watcher.
+
+set -uo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$HOME/.local/share/Panama}"
+SETTINGS="${PANAMA_AGENT_SETTINGS:-${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json}"
+
+# systemd-coredump's MESSAGE_ID. Matching on this rather than on text keeps
+# working when the wording changes and never matches a program that merely
+# mentions the word "crash" in its own logs.
+readonly COREDUMP_MESSAGE_ID='fc2e22bc6ee647b6b90729ab34a250b1'
+
+command -v journalctl >/dev/null 2>&1 || exit 0
+command -v notify-send >/dev/null 2>&1 || exit 0
+
+# The shell owns org.freedesktop.Notifications, and the crash most worth
+# reporting is the one that took the shell with it. Waiting means that report
+# arrives rather than vanishing into a bus nobody is serving.
+for _ in $(seq 1 60); do
+    busctl --user status org.freedesktop.Notifications >/dev/null 2>&1 && break
+    sleep 1
+done
+
+# Read per crash rather than once at startup, so choosing an agent in Settings
+# takes effect on the next crash instead of on the next login. This service runs
+# for the life of the session; nothing restarts it when a preference changes.
+read_setting() {
+    local key="$1" fallback="$2"
+    [[ -r "$SETTINGS" ]] || { printf '%s' "$fallback"; return; }
+    command -v jq >/dev/null 2>&1 || { printf '%s' "$fallback"; return; }
+    jq -r --arg k "$key" --arg d "$fallback" \
+        'if has($k) and (.[$k] != null) then (.[$k] | tostring) else $d end' \
+        "$SETTINGS" 2>/dev/null || printf '%s' "$fallback"
+}
+
+# What to call the agent in a sentence aimed at a person.
+agent_label() {
+    case "$1" in
+        claude) printf 'Claude Code' ;;
+        codex) printf 'Codex' ;;
+        *) printf '%s' "$1" ;;
+    esac
+}
+
+declare -A reported=()
+
+# -f from now, not from the boot: a session that starts after a crash should
+# not open with a notification about something the user has already lived
+# through and cannot act on.
+journalctl --user -f -n 0 --output=json MESSAGE_ID="$COREDUMP_MESSAGE_ID" 2>/dev/null \
+    | while IFS= read -r line; do
+        [[ -n "$line" ]] || continue
+
+        # One jq per entry rather than one per field: the fields are read
+        # together, and the click payload needs all of them.
+        IFS=$'\t' read -r uid exe comm pid signal < <(
+            jq -r '[(.COREDUMP_UID // ""),
+                    (.COREDUMP_EXE // ""),
+                    (.COREDUMP_COMM // ""),
+                    (.COREDUMP_PID // ""),
+                    (.COREDUMP_SIGNAL_NAME // "")] | @tsv' <<<"$line" 2>/dev/null
+        )
+
+        # Another user's crash is not this session's business, and reporting it
+        # would leak what they are running.
+        [[ "$uid" == "$(id -u)" ]] || continue
+        [[ -n "$exe" || -n "$comm" ]] || continue
+
+        # The executable name first: COREDUMP_COMM is the kernel's comm field
+        # and is truncated to fifteen characters, so it reports
+        # "panama-test-cra" for a program called panama-test-crasher.
+        if [[ -n "$exe" ]]; then
+            program="$(basename "$exe")"
+        else
+            program="$comm"
+        fi
+
+        # Never announce our own machinery. A crash watcher that notifies about
+        # the crash watcher, or about the agent it just launched to investigate
+        # the last crash, is a loop with a toast in it.
+        [[ "$program" == panama-crash-* || "$program" == panama-agent* ]] && continue
+
+        [[ -z "${reported[$program]:-}" ]] || continue
+        reported[$program]=1
+
+        # The toast can only offer a diagnosis if there is something to diagnose
+        # with. No agent, or the offer switched off, and it stays exactly the
+        # actionless notification it has always been.
+        agent="$(read_setting preferredAgent none)"
+        offer="$(read_setting crashDiagnoseOffer true)"
+
+        if [[ -n "$agent" && "$agent" != "none" && "$offer" != "false" && "$pid" =~ ^[0-9]+$ ]]; then
+            # By absolute path, not by name. The shell runs this hint, and the
+            # shell is started by systemd -- whose environment does not carry
+            # the repository's bin directory on PATH, so a bare name would
+            # click into "command not found".
+            exec_command="$(printf '%q %q %q %q %q' \
+                "$PANAMA_PATH/bin/panama-agent-crash" \
+                "$pid" "${comm:-$program}" "${exe:-unknown}" "${signal:-unknown}")"
+
+            # The hint is data, not privilege. Any process on this session bus
+            # could send one, and running it grants nothing a local process
+            # could not already do for itself.
+            # Same urgency as the plain report, deliberately. Making the
+            # clickable one critical would let a crash break through Do Not
+            # Disturb, which is a louder desktop than anybody asked for in
+            # exchange for an offer that keeps until it is read anyway.
+            notify-send --icon=dialog-error-symbolic --app-name=Panama \
+                --hint="string:panama-exec:$exec_command" \
+                "$program stopped unexpectedly" \
+                "Click to diagnose with $(agent_label "$agent")." \
+                2>/dev/null || true
+        else
+            notify-send --icon=dialog-error-symbolic --app-name=Panama \
+                "$program stopped unexpectedly" \
+                "It crashed and was not able to recover. System Health has the details." \
+                2>/dev/null || true
+        fi
+    done
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+# Stamps a new migration, so the name is never chosen by hand.
+#
+#   panama-dev-migration "remove the stale settings-ssh-keys.sh launcher command"
+#
+# The filename is the commit timestamp of HEAD, which makes glob order
+# chronological without a sequence number that two branches could pick at the
+# same time. Two migrations authored against the same commit would collide, so
+# a taken name gets the next free second rather than silently overwriting.
+#
+# Developer tool, not part of any install path. See bin/panama-migrate for what
+# runs these and what rules they have to follow.
+
+set -euo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
+MIGRATIONS_DIR="$PANAMA_PATH/migrations"
+
+describe="${1:-}"
+if [[ -z "$describe" ]]; then
+    echo 'usage: panama-dev-migration "what this repairs"' >&2
+    exit 2
+fi
+
+stamp="$(git -C "$PANAMA_PATH" log -1 --format=%cd --date=unix 2>/dev/null || date +%s)"
+mkdir -p "$MIGRATIONS_DIR"
+while [[ -e "$MIGRATIONS_DIR/$stamp.sh" ]]; do
+    stamp=$(( stamp + 1 ))
+done
+file="$MIGRATIONS_DIR/$stamp.sh"
+
+cat >"$file" <<EOF
+#!/usr/bin/env bash
+
+# $describe
+#
+# Rules, because the runner cannot enforce them:
+#
+#   * Safe to run twice. The marker records success, not intent.
+#   * Tolerant of the repair already being correct -- the user may have fixed
+#     it by hand, or a later ./install may have put it back.
+#   * Root work goes through \`panama-sudo --reason "..."\`, never bare sudo,
+#     so the password prompt names the repair.
+#   * Exit non-zero to be retried at the next login. Exit zero only when the
+#     machine is genuinely in the state this describes.
+
+set -euo pipefail
+
+PANAMA_PATH="\${PANAMA_PATH:-\$HOME/.local/share/Panama}"
+
+# ... the repair goes here.
+EOF
+
+chmod +x "$file"
+printf 'Created %s\n' "$file"
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+# The pressure valve.
+#
+#   panama-hook theme-set dark orchid
+#
+# Runs ~/.config/panama/hooks/<name> and everything executable in
+# ~/.config/panama/hooks/<name>.d/, in sorted order, with the hook's arguments.
+#
+# This exists so "can Panama also do X when the theme changes" is a five-line
+# file somebody drops in a directory rather than a fork, a feature request, or
+# a patch that has to be rebased forever. docs/UPSTREAM-INSPIRATION.md defers a
+# plugin host as premature and still should: this is the thirty-line version
+# that covers most of what people actually want from one, and it has no API to
+# keep stable beyond "we will run your script and tell you what happened".
+#
+# A failing hook is reported and stepped over. Somebody's broken script must
+# never break a theme change, an upgrade, or a login -- which is exactly what
+# would happen if this used `set -e` and the caller did too.
+#
+# Hooks run synchronously, so a slow one delays whatever called it. That is
+# deliberate: the alternative is a hook whose output arrives after the thing it
+# was reacting to has already finished, which is harder to reason about than a
+# pause.
+
+set -uo pipefail
+
+HOOK_DIR="${PANAMA_HOOK_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/panama/hooks}"
+
+name="${1:-}"
+if [[ -z "$name" ]]; then
+    echo 'usage: panama-hook <name> [args...]' >&2
+    exit 2
+fi
+shift
+
+# A hook name reaches the filesystem, so it cannot be allowed to leave the
+# directory. Callers are all in-repo today, which is exactly when this is
+# cheap to add and easy to forget.
+if [[ ! "$name" =~ ^[a-z][a-z0-9-]*$ ]]; then
+    echo "panama-hook: refusing hook name: $name" >&2
+    exit 2
+fi
+
+run_one() {
+    local script="$1"
+    # Shifted off before the arguments are forwarded, or every hook receives
+    # its own path as $1 and the real arguments arrive one place late.
+    shift
+    [[ -f "$script" && -x "$script" ]] || return 0
+    if ! "$script" "$@"; then
+        printf 'panama-hook: %s failed (%s); continuing\n' \
+            "$(basename "$script")" "$name" >&2
+    fi
+}
+
+# The single file first, then the .d directory in sorted order. Both are
+# optional and having neither is the normal case.
+run_one "$HOOK_DIR/$name" "$@"
+
+if [[ -d "$HOOK_DIR/$name.d" ]]; then
+    while IFS= read -r script; do
+        [[ -n "$script" ]] || continue
+        run_one "$script" "$@"
+    done < <(find "$HOOK_DIR/$name.d" -maxdepth 1 -type f | sort)
+fi
+
+exit 0
@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+
+# What this machine is, asked one yes-or-no question at a time.
+#
+#   panama-hw laptop && echo "portable"
+#   panama-hw clamshell && panama-lid close
+#
+# Every subcommand exits 0 for yes and 1 for no, prints nothing, and answers
+# correctly on a machine that has none of the hardware in question. That last
+# part is the whole point: a desktop must be able to ask "am I in clamshell
+# mode" and get a calm no rather than an error, because the scripts and
+# services that ask are shared between machines.
+#
+# `--json` answers everything at once, for the health page and for contracts.
+#
+# Detection reads sysfs directly rather than shelling out to lspci or upower:
+# lspci touches PCI config space and wakes a runtime-suspended GPU, which is a
+# real cost to pay for a question asked at every login.
+#
+# Paths are overridable (PANAMA_HW_SYS, PANAMA_HW_ACPI) so the contract can
+# drive fixture trees. Nothing else should set them.
+
+set -uo pipefail
+
+SYS="${PANAMA_HW_SYS:-/sys}"
+ACPI="${PANAMA_HW_ACPI:-/proc/acpi}"
+
+# SMBIOS chassis types that mean "carried around": Portable, Laptop, Notebook,
+# Hand Held, Sub Notebook, Tablet, Convertible, Detachable. A machine that
+# reports something else, or reports nothing, is treated as stationary --
+# guessing "laptop" on an unknown chassis would put battery chrome on a desktop.
+readonly PORTABLE_CHASSIS=" 8 9 10 11 14 30 31 32 "
+
+is_laptop() {
+    local type_file="$SYS/class/dmi/id/chassis_type" chassis
+    [[ -r "$type_file" ]] || return 1
+    chassis="$(cat "$type_file" 2>/dev/null)" || return 1
+    [[ "$PORTABLE_CHASSIS" == *" $chassis "* ]]
+}
+
+# The first SYSTEM battery, or nothing. Named rather than assumed to be BAT0:
+# the second battery in a ThinkPad is BAT1, and a machine with only BAT1
+# exists. The scope check is what keeps a desktop a desktop: a wireless mouse
+# or a game controller publishes type=Battery with scope=Device, and counting
+# one turned a tower into a "laptop" whose battery readout was the mouse's.
+battery_path() {
+    local supply type scope
+    for supply in "$SYS"/class/power_supply/*; do
+        [[ -r "$supply/type" ]] || continue
+        type="$(cat "$supply/type" 2>/dev/null)"
+        [[ "$type" == "Battery" ]] || continue
+        scope="$(cat "$supply/scope" 2>/dev/null || echo System)"
+        [[ "$scope" == "Device" ]] && continue
+        printf '%s\n' "$supply"
+        return 0
+    done
+    return 1
+}
+
+has_battery() { battery_path >/dev/null; }
+
+# On wall power. A machine with no mains supply at all and no system battery
+# is a desktop, and a desktop is always on wall power -- answering "no" there
+# would make every battery-aware timing apply to a machine that cannot run
+# out of power. But "no Mains" alone is not "desktop": hardware charged only
+# over USB-PD exposes type=USB supplies and no Mains at all, and reading that
+# as permanently-on-AC meant its battery timings never engaged while it ran
+# down. When no Mains exists but a system battery does, the battery's own
+# status is the answer: Discharging means battery, everything else means fed.
+on_ac() {
+    local supply type online found=1 battery status
+    for supply in "$SYS"/class/power_supply/*; do
+        [[ -r "$supply/type" ]] || continue
+        type="$(cat "$supply/type" 2>/dev/null)"
+        [[ "$type" == "Mains" ]] || continue
+        found=0
+        online="$(cat "$supply/online" 2>/dev/null || echo 0)"
+        [[ "$online" == "1" ]] && return 0
+    done
+    # Mains exists and none of it is online: genuinely on battery.
+    (( found == 0 )) && return 1
+    if battery="$(battery_path)"; then
+        status="$(cat "$battery/status" 2>/dev/null || echo Unknown)"
+        [[ "$status" == "Discharging" ]] && return 1
+    fi
+    return 0
+}
+
+# ACPI first, logind second. Some platforms expose the lid only as an evdev
+# switch with no /proc/acpi/button entry; logind watches the switch either
+# way, so its LidClosed property is the fallback that keeps clamshell
+# detection honest there. No logind (a container, a test tree) means the
+# fallback quietly answers open, which is the safe direction.
+lid_closed() {
+    local state
+    for state in "$ACPI"/button/lid/*/state; do
+        [[ -r "$state" ]] || continue
+        grep -qi closed "$state" && return 0
+        return 1
+    done
+    [[ -d "$ACPI/button/lid" ]] && return 1
+    busctl get-property org.freedesktop.login1 /org/freedesktop/login1 \
+        org.freedesktop.login1.Manager LidClosed 2>/dev/null | grep -q 'b true'
+}
+
+# A connected output that is not the built-in panel. eDP, LVDS and DSI are the
+# internal ones; everything else arrived through a cable.
+has_external_monitor() {
+    local status connector
+    for status in "$SYS"/class/drm/card*-*/status; do
+        [[ -r "$status" ]] || continue
+        [[ "$(cat "$status" 2>/dev/null)" == "connected" ]] || continue
+        connector="$(basename "$(dirname "$status")")"
+        case "$connector" in
+            *eDP*|*LVDS*|*DSI*) continue ;;
+            *) return 0 ;;
+        esac
+    done
+    return 1
+}
+
+# The one definition the rest of the laptop work hangs on: the lid is shut and
+# there is still a screen to use. Closing the lid on a dock must not suspend;
+# closing it on a train must.
+is_clamshell() { lid_closed && has_external_monitor; }
+
+has_touchpad() {
+    local name
+    for name in "$SYS"/class/input/*/name; do
+        [[ -r "$name" ]] || continue
+        grep -qi touchpad "$name" && return 0
+    done
+    return 1
+}
+
+# Vendor 0x10de on a display-class device. Read from sysfs rather than lspci
+# so an idle discrete GPU is not woken to answer.
+has_nvidia() {
+    local device vendor class
+    for device in "$SYS"/bus/pci/devices/*; do
+        [[ -r "$device/vendor" && -r "$device/class" ]] || continue
+        vendor="$(cat "$device/vendor" 2>/dev/null)"
+        [[ "$vendor" == "0x10de" ]] || continue
+        class="$(cat "$device/class" 2>/dev/null)"
+        [[ "$class" == 0x03* ]] && return 0
+    done
+    return 1
+}
+
+answer() { "$1" && printf 'true' || printf 'false'; }
+
+cmd_json() {
+    printf '{"laptop":%s,"battery":%s,"ac":%s,"lidClosed":%s,"externalMonitor":%s,"clamshell":%s,"touchpad":%s,"nvidia":%s}\n' \
+        "$(answer is_laptop)" "$(answer has_battery)" "$(answer on_ac)" \
+        "$(answer lid_closed)" "$(answer has_external_monitor)" \
+        "$(answer is_clamshell)" "$(answer has_touchpad)" "$(answer has_nvidia)"
+}
+
+case "${1:-}" in
+    laptop)           is_laptop ;;
+    battery)          has_battery ;;
+    battery-path)     battery_path ;;
+    ac)               on_ac ;;
+    lid-closed)       lid_closed ;;
+    external-monitor) has_external_monitor ;;
+    clamshell)        is_clamshell ;;
+    touchpad)         has_touchpad ;;
+    nvidia)           has_nvidia ;;
+    --json)           cmd_json ;;
+    -h|--help|"")
+        cat <<'USAGE'
+usage: panama-hw <predicate>
+
+Exits 0 for yes, 1 for no, and prints nothing.
+
+  laptop            a portable chassis
+  battery           a battery is present
+  battery-path      print the first battery's sysfs path (0 if found)
+  ac                on wall power (a machine with no mains is always yes)
+  lid-closed        the lid is shut
+  external-monitor  a connected output that is not the built-in panel
+  clamshell         lid shut AND an external monitor: docked, keep working
+  touchpad          a touchpad is present
+  nvidia            an NVIDIA display device is present
+
+  --json            every answer at once
+USAGE
+        ;;
+    *) printf 'panama-hw: unknown predicate: %s\n' "$1" >&2; exit 2 ;;
+esac
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+# Focus the window if it is already open; start it if it is not.
+#
+#   panama-launch --class '^helium$' -- helium-browser-bin
+#   panama-launch --class '^kitty$' --title 'nvim' -- kitty nvim .
+#
+# This is what the application keys do on every other desktop. Pressing the
+# browser key twice on macOS or Windows raises the browser; here it used to
+# open a second one, which is the single most common "Linux feels wrong"
+# moment and a twenty-line fix.
+#
+# Matching is a regular expression against the window class, optionally
+# narrowed by title. Both halves matter: the terminal and the editor are both
+# kitty on this desktop, and only the title tells them apart -- so a class-only
+# match would make the editor key raise whatever terminal happened to be open.
+#
+# Anchor your patterns. `--class mail` would match `gmail-notifier`, and the
+# key that should open Thunderbird would raise somebody's notifier instead.
+
+set -uo pipefail
+
+class_pattern=""
+title_pattern=""
+
+while (( $# > 0 )); do
+    case "$1" in
+        --class) class_pattern="${2:-}"; shift 2 ;;
+        --title) title_pattern="${2:-}"; shift 2 ;;
+        --)      shift; break ;;
+        *)       break ;;
+    esac
+done
+
+if [[ -z "$class_pattern" || $# -eq 0 ]]; then
+    echo 'usage: panama-launch --class <regex> [--title <regex>] -- command [args...]' >&2
+    exit 2
+fi
+
+launch() {
+    # setsid so the application outlives this script and is not a child of the
+    # compositor's exec, which would tie its lifetime to a shell that exits.
+    setsid "$@" >/dev/null 2>&1 &
+    exit 0
+}
+
+# No compositor, no window list: just start the thing.
+command -v hyprctl >/dev/null 2>&1 || launch "$@"
+
+address="$(hyprctl clients -j 2>/dev/null | jq -r --arg class "$class_pattern" --arg title "$title_pattern" '
+    [ .[]
+      | select(.mapped)
+      | select(.class | test($class))
+      | select($title == "" or (.title | test($title)))
+    ]
+    # Most recently focused first: with several matches, raise the one the
+    # user was last in rather than whichever the compositor lists first.
+    | sort_by(-.focusHistoryID)
+    | .[0].address // empty
+' 2>/dev/null)"
+
+if [[ -n "$address" ]]; then
+    # Hyprland 0.56 dispatches through Lua: `hyprctl dispatch focuswindow
+    # address:0x...` is parsed as Lua source and fails. The selector string is
+    # what hl.focus accepts; a table of the same fields is refused.
+    exec hyprctl dispatch "hl.dsp.focus({ window = \"address:$address\" })"
+fi
+
+launch "$@"
@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+
+# Bringing an already-installed machine up to what this checkout expects.
+#
+# `./install` is additive: it copies files over `/`, links dotfiles, and
+# installs packages. It has no way to say "remove that file", "disable that
+# unit", "that symlink now points at the wrong place". So a machine installed
+# in March keeps March's mistakes forever, and the only thing that ever fixes
+# them is the person who happens to read a commit message.
+#
+# A migration is one shell script that performs one such repair, exactly once,
+# on machines that need it.
+#
+#   migrations/<unix-timestamp>.sh
+#
+# The name is the commit timestamp of HEAD when it was authored, so glob order
+# over fixed-width epoch seconds IS chronological order -- no sequence numbers
+# to collide on across branches. `panama-dev-migration` stamps them.
+#
+# State is one empty marker file per migration under
+# $XDG_STATE_HOME/panama/migrations. Present means applied. There is no
+# database and no version integer, because the failure mode of a version
+# integer is that one bad migration strands every later one behind it.
+#
+# The rules a migration must follow are in the template that
+# `panama-dev-migration` writes, and they are worth repeating here because
+# this runner cannot enforce them:
+#
+#   * Safe to run twice. The marker only records that it succeeded once.
+#   * Tolerant of the repair already being correct -- a user may have fixed it
+#     by hand, or a later `./install` may have overwritten it back.
+#   * Root work goes through `panama-sudo --reason "..."`, never bare sudo,
+#     so the prompt names the repair. See bin/panama-sudo.
+#
+# The marker is written ONLY on success, so a migration that fails stays
+# pending and is retried at the next login. That is deliberate: a repair that
+# could not complete has not happened, and recording it as done would hide it
+# forever.
+#
+# This mirrors config/dot/quickshell/config/Migrations.qml, which does the same
+# job for the settings JSON and documents the same reasoning. That one handles
+# renamed preference keys; this one handles everything else.
+
+set -uo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
+MIGRATIONS_DIR="$PANAMA_PATH/migrations"
+STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/panama/migrations"
+
+export PANAMA_PATH
+
+info() { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
+ok()   { printf '\033[1;32m✓\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m!\033[0m %s\n' "$*" >&2; }
+err()  { printf '\033[1;31m✗\033[0m %s\n' "$*" >&2; }
+
+# Every migration this checkout ships, oldest first. Empty is a valid state.
+all_migrations() {
+    [[ -d "$MIGRATIONS_DIR" ]] || return 0
+    local file
+    for file in "$MIGRATIONS_DIR"/*.sh; do
+        [[ -e "$file" ]] || continue
+        basename "$file"
+    done | sort
+}
+
+pending_migrations() {
+    local name
+    while read -r name; do
+        [[ -n "$name" ]] || continue
+        [[ -e "$STATE_DIR/$name" ]] || printf '%s\n' "$name"
+    done < <(all_migrations)
+}
+
+run_one() {
+    local name="$1" file="$MIGRATIONS_DIR/$1"
+    info "$name"
+    # A subshell with its own strictness: a migration that forgets `set -e` is
+    # still stopped by its first failing command, and one that sets shell
+    # options cannot leak them into the next migration.
+    if bash -euo pipefail "$file"; then
+        mkdir -p "$STATE_DIR"
+        : >"$STATE_DIR/$name"
+        ok "$name applied"
+        return 0
+    fi
+    err "$name failed and will be retried at the next login"
+    return 1
+}
+
+cmd_run() {
+    local pending
+    pending="$(pending_migrations)"
+    if [[ -z "$pending" ]]; then
+        ok "Nothing to migrate; this machine matches the checkout."
+        return 0
+    fi
+
+    local count failed=0 name
+    count="$(grep -c . <<<"$pending")"
+    info "$count migration(s) to apply"
+    while read -r name; do
+        [[ -n "$name" ]] || continue
+        # Stop at the first failure rather than continuing. Migrations are
+        # ordered, and a later one may assume an earlier one landed; running
+        # it anyway turns one stuck repair into an unpredictable machine.
+        if ! run_one "$name"; then
+            failed=1
+            break
+        fi
+    done <<<"$pending"
+
+    if (( failed )); then
+        warn "Re-running 'panama migrate' is safe and will retry from the failure."
+        warn "If it keeps failing, hand it to an agent: panama diagnose"
+        return 1
+    fi
+    ok "This machine now matches the checkout."
+    # Only after repairs actually ran: a hook that fires on every login when
+    # there was nothing to do is a hook people disable.
+    "$PANAMA_PATH/bin/panama-hook" post-migrate || true
+}
+
+# The check the login notifier runs. Exit 0 means work is waiting, so it reads
+# as `if panama-migrate --pending; then notify; fi`.
+cmd_pending() {
+    local pending
+    pending="$(pending_migrations)"
+    [[ -n "$pending" ]] || return 1
+    grep -c . <<<"$pending"
+}
+
+cmd_list() {
+    local name
+    while read -r name; do
+        [[ -n "$name" ]] || continue
+        if [[ -e "$STATE_DIR/$name" ]]; then
+            printf 'applied  %s\n' "$name"
+        else
+            printf 'pending  %s\n' "$name"
+        fi
+    done < <(all_migrations)
+}
+
+# Re-run one that already succeeded. For developing a migration, and for the
+# rare case where a repair was undone by something else.
+cmd_force() {
+    local name="${1:-}"
+    [[ -n "$name" ]] || { err "force needs a migration name"; return 2; }
+    [[ -e "$MIGRATIONS_DIR/$name" ]] || { err "no such migration: $name"; return 2; }
+    rm -f "$STATE_DIR/$name"
+    run_one "$name"
+}
+
+# Mark everything applied without running it. This is what a fresh install
+# does: the machine was just built from this checkout, so every repair those
+# migrations describe is already true of it, and running them would apply
+# fixes for versions it never had.
+cmd_baseline() {
+    mkdir -p "$STATE_DIR"
+    local name count=0
+    while read -r name; do
+        [[ -n "$name" ]] || continue
+        [[ -e "$STATE_DIR/$name" ]] && continue
+        : >"$STATE_DIR/$name"
+        count=$(( count + 1 ))
+    done < <(all_migrations)
+    ok "Marked $count migration(s) as already applied."
+}
+
+case "${1:-run}" in
+    run)        shift || true; cmd_run "$@" ;;
+    --pending)  shift || true; cmd_pending "$@" ;;
+    --list|list) shift || true; cmd_list "$@" ;;
+    --force)    shift || true; cmd_force "$@" ;;
+    --baseline) shift || true; cmd_baseline "$@" ;;
+    -h|--help)
+        cat <<'USAGE'
+usage: panama-migrate [run|--pending|--list|--force <name>|--baseline]
+
+  run         Apply every pending migration, oldest first (default)
+  --pending   Exit 0 and print the count when work is waiting, else exit 1
+  --list      Show every migration and whether it has been applied
+  --force     Re-run one migration that already succeeded
+  --baseline  Mark everything applied without running it (fresh installs)
+USAGE
+        ;;
+    *) err "unknown argument: $1"; exit 2 ;;
+esac
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+# "Panama has repairs waiting for this machine."
+#
+# A migration that nobody knows about is a migration that never runs. This
+# checks once per session and, when work is pending, sends one notification
+# whose action opens a terminal running `panama migrate` -- so the repair is
+# always something the user chose, never something that happened to them.
+#
+# Waiting for the notification server first is not politeness. Quickshell owns
+# org.freedesktop.Notifications, and a shell that has not started yet would
+# swallow this silently -- which is precisely the session where a pending
+# migration is most likely to matter.
+
+set -uo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
+TERMINAL="${PANAMA_TERMINAL:-kitty}"
+
+command -v notify-send >/dev/null 2>&1 || exit 1
+
+count="$("$PANAMA_PATH/bin/panama-migrate" --pending)" || exit 1
+[[ -n "$count" ]] || exit 1
+
+# Up to ~15s for the shell to claim the bus name. Longer than a healthy start
+# needs, short enough that a session without a shell gives up rather than
+# lingering.
+for _ in $(seq 1 30); do
+    if busctl --user status org.freedesktop.Notifications >/dev/null 2>&1; then
+        break
+    fi
+    sleep 0.5
+done
+
+if (( count == 1 )); then
+    body="One repair is waiting for this machine."
+else
+    body="$count repairs are waiting for this machine."
+fi
+
+# Critical so it waits to be read: a notification that expires while the user
+# is elsewhere has told nobody anything. The action is the whole point -- there
+# is no instruction to remember and nothing to type.
+action="$(notify-send --urgency=critical --icon=system-software-update \
+    --app-name=Panama \
+    --action=migrate="Apply now" --action=later="Later" \
+    "Panama updates" "$body" 2>/dev/null)" || exit 0
+
+[[ "$action" == "migrate" ]] || exit 0
+exec "$TERMINAL" --hold "$PANAMA_PATH/bin/panama-migrate" run
@@ -0,0 +1,323 @@
+#!/usr/bin/env bash
+#
+# panama-server – the compose services a server machine runs.
+#
+# The repository carries the catalog: server/containers/<Name>/ holds a
+# compose.yml, a podman-<name>.service user unit, and an .env.example naming
+# what the service needs told. The machine carries the rest: ~/Server/<Name>/
+# is a real directory owning the .env (secrets never sit inside the checkout,
+# gitignored or not) and the bind-mounted data. Only the tracked files are
+# symlinked, so a `git clean` in the repo can never reach a database.
+#
+#   list             every service in the catalog, with its state here
+#   enable <Name>    link it into ~/Server, seed .env, enable the unit
+#   disable <Name>   stop it and remove the unit; data and .env stay put
+#   status [<Name>]  what is actually running
+#   relink           refresh the symlinks for everything enabled here
+#
+# Verbs act on the unit and the links, never on data: there is deliberately no
+# verb here that deletes ~/Server/<Name> or anything in it.
+
+set -uo pipefail
+
+PROGRAM="panama server"
+
+SCRIPT_PATH=$(readlink -f "${BASH_SOURCE[0]}")
+PANAMA_DIR=$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)
+
+# Overridable so the contract can point this at a fixture catalog and a
+# throwaway HOME rather than the machine's real services.
+SERVER_DIR="${PANAMA_SERVER_DIR:-$PANAMA_DIR/server/containers}"
+TARGET_DIR="${PANAMA_SERVER_TARGET:-$HOME/Server}"
+UNIT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+STATE_FILE="${XDG_STATE_HOME:-$HOME/.local/state}/panama/server-definitions"
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ $(tput colors 2>/dev/null || echo 0) -ge 8 ]]; then
+  BOLD=$(tput bold); RESET=$(tput sgr0)
+  RED=$(tput setaf 1); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); BLUE=$(tput setaf 4)
+else
+  BOLD=""; RESET=""; RED=""; GREEN=""; YELLOW=""; BLUE=""
+fi
+
+info()  { printf '%s==>%s %s\n'  "${BLUE}${BOLD}"   "$RESET" "$*"; }
+ok()    { printf '%s✓%s %s\n'    "${GREEN}${BOLD}"  "$RESET" "$*"; }
+warn()  { printf '%s!%s %s\n'    "${YELLOW}${BOLD}" "$RESET" "$*"; }
+err()   { printf '%s✗%s %s\n'    "${RED}${BOLD}"    "$RESET" "$*" >&2; }
+
+usage() {
+  cat <<EOF
+${BOLD}$PROGRAM${RESET} – manage the compose services in server/containers/
+
+${BOLD}Usage:${RESET}
+  $PROGRAM list             Every service in the catalog, and its state here
+  $PROGRAM enable <Name>    Link a service into ~/Server, seed its .env from
+                            .env.example, and enable its unit. Stops short of
+                            starting when the .env still holds CHANGE_ME
+                            placeholders, and says which.
+  $PROGRAM disable <Name>   Stop the unit and unlink it. ~/Server/<Name>,
+                            its .env and its data are never touched.
+  $PROGRAM status [<Name>]  What is actually running, per service
+  $PROGRAM relink           Refresh every enabled service's symlinks after a
+                            pull, and name the ones whose definitions changed
+                            (nothing is restarted for you)
+EOF
+}
+
+# ── The catalog ──────────────────────────────────────────────────────────────
+
+services() {
+  local dir
+  for dir in "$SERVER_DIR"/*/; do
+    [[ -d "$dir" ]] || continue
+    basename "$dir"
+  done
+}
+
+require_service() {
+  local name="$1"
+  if [[ ! -d "$SERVER_DIR/$name" ]]; then
+    err "No such service: '$name'"
+    printf 'The catalog has:\n' >&2
+    services | sed 's/^/  /' >&2
+    exit 1
+  fi
+}
+
+# The one unit file a service directory carries. Its filename is its identity
+# -- podman-<name>.service, exactly what lands in the systemd user directory --
+# so nothing here invents a name that could drift from the file's.
+unit_path_for() {
+  local name="$1" unit
+  for unit in "$SERVER_DIR/$name"/*.service; do
+    [[ -e "$unit" ]] || continue
+    printf '%s' "$unit"
+    return 0
+  done
+  return 1
+}
+
+unit_name_for() {
+  local unit
+  unit="$(unit_path_for "$1")" || return 1
+  basename "$unit"
+}
+
+# Installed means our symlink is in the systemd user directory. A regular file
+# of the same name is a pre-Panama install done by hand -- reported, never
+# silently replaced.
+unit_installed() {
+  local unit_name
+  unit_name="$(unit_name_for "$1")" || return 1
+  [[ -L "$UNIT_DIR/$unit_name" ]]
+}
+
+definition_hash() {
+  local name="$1" unit
+  unit="$(unit_path_for "$name")" || unit=/dev/null
+  cat "$SERVER_DIR/$name/compose.yml" "$unit" 2>/dev/null | sha256sum | cut -d' ' -f1
+}
+
+recorded_hash() {
+  [[ -r "$STATE_FILE" ]] || return 0
+  awk -v name="$1" '$1 == name {print $2}' "$STATE_FILE"
+}
+
+record_hash() {
+  local name="$1" hash="$2"
+  mkdir -p "$(dirname "$STATE_FILE")"
+  { [[ -r "$STATE_FILE" ]] && awk -v name="$name" '$1 != name' "$STATE_FILE"; \
+    printf '%s %s\n' "$name" "$hash"; } >"$STATE_FILE.tmp"
+  mv "$STATE_FILE.tmp" "$STATE_FILE"
+}
+
+# Replace path with a symlink to src. An existing regular file is moved aside
+# with its name intact plus a suffix, because the only regular file that can be
+# here is a pre-Panama one somebody wrote by hand -- worth keeping to diff.
+link_file() {
+  local src="$1" path="$2"
+  if [[ -L "$path" ]]; then
+    [[ "$(readlink -f "$path")" == "$(readlink -f "$src")" ]] && return 0
+    rm "$path"
+  elif [[ -e "$path" ]]; then
+    mv "$path" "$path.pre-panama"
+    warn "Kept the existing $(basename "$path") as $(basename "$path").pre-panama"
+  fi
+  ln -s "$src" "$path"
+}
+
+# ── Verbs ────────────────────────────────────────────────────────────────────
+
+cmd_list() {
+  local name unit_name state enabled
+  for name in $(services); do
+    unit_name="$(unit_name_for "$name")" || { printf '%-24s %s\n' "$name" "no unit file"; continue; }
+    if unit_installed "$name"; then
+      state="$(systemctl --user is-active "$unit_name" 2>/dev/null || true)"
+      enabled="enabled"
+      [[ "$state" == active ]] && state="${GREEN}active${RESET}" || state="${YELLOW}${state:-unknown}${RESET}"
+      printf '%-24s %s, %b\n' "$name" "$enabled" "$state"
+    elif [[ -e "$UNIT_DIR/$unit_name" ]]; then
+      printf '%-24s %s\n' "$name" "installed by hand (not Panama's symlink)"
+    else
+      printf '%-24s %s\n' "$name" "-"
+    fi
+  done
+}
+
+cmd_enable() {
+  local name="${1:-}"
+  [[ -n "$name" ]] || { err "Which service? Usage: $PROGRAM enable <Name>"; exit 1; }
+  require_service "$name"
+
+  local repo_dir="$SERVER_DIR/$name" live_dir="$TARGET_DIR/$name"
+  [[ -f "$repo_dir/compose.yml" ]] || { err "$name has no compose.yml in the catalog"; exit 1; }
+  local unit_path unit_name
+  unit_path="$(unit_path_for "$name")" || { err "$name has no unit file in the catalog"; exit 1; }
+  unit_name="$(basename "$unit_path")"
+
+  mkdir -p "$live_dir"
+  link_file "$repo_dir/compose.yml" "$live_dir/compose.yml"
+  ok "Linked compose.yml → $live_dir/compose.yml"
+
+  # The .env lives with the machine, not the checkout. Seeded once from the
+  # example and never overwritten -- it is where the person's secrets go.
+  if [[ -f "$repo_dir/.env.example" && ! -e "$live_dir/.env" ]]; then
+    cp "$repo_dir/.env.example" "$live_dir/.env"
+    chmod 600 "$live_dir/.env"
+    ok "Seeded $live_dir/.env from .env.example"
+  fi
+
+  # Refusing to start on placeholders, and saying which: a service brought up
+  # with CHANGE_ME as its database password does not fail loudly, it runs --
+  # and what it runs is a service whose password is CHANGE_ME.
+  if [[ -e "$live_dir/.env" ]] && grep -q 'CHANGE_ME' "$live_dir/.env"; then
+    warn "$live_dir/.env still has placeholder values:"
+    grep -n 'CHANGE_ME' "$live_dir/.env" | sed 's/^/    /'
+    printf 'Fill them in, then run: %s enable %s\n' "$PROGRAM" "$name"
+    exit 1
+  fi
+
+  mkdir -p "$UNIT_DIR"
+  link_file "$unit_path" "$UNIT_DIR/$unit_name"
+  systemctl --user daemon-reload
+  if systemctl --user enable --now "$unit_name"; then
+    record_hash "$name" "$(definition_hash "$name")"
+    ok "$name enabled and started ($unit_name)"
+  else
+    err "$unit_name did not start; see: systemctl --user status $unit_name"
+    exit 1
+  fi
+}
+
+cmd_disable() {
+  local name="${1:-}"
+  [[ -n "$name" ]] || { err "Which service? Usage: $PROGRAM disable <Name>"; exit 1; }
+  require_service "$name"
+  local unit_name
+  unit_name="$(unit_name_for "$name")" || { err "$name has no unit file in the catalog"; exit 1; }
+
+  systemctl --user disable --now "$unit_name" 2>/dev/null || true
+  if [[ -L "$UNIT_DIR/$unit_name" ]]; then
+    rm "$UNIT_DIR/$unit_name"
+    systemctl --user daemon-reload
+  fi
+  ok "$name disabled. ~/Server/$name, its .env and its data were not touched."
+}
+
+cmd_status() {
+  local name="${1:-}"
+  if [[ -n "$name" ]]; then
+    require_service "$name"
+    local unit_name
+    unit_name="$(unit_name_for "$name")" || { err "$name has no unit file"; exit 1; }
+    systemctl --user status --no-pager "$unit_name" || true
+    if [[ -d "$TARGET_DIR/$name" ]]; then
+      ( cd "$TARGET_DIR/$name" && podman compose ps 2>/dev/null ) || true
+    fi
+    return 0
+  fi
+
+  # The role's health summary: what is enabled here, and is it actually up.
+  local any=0 unit_name state
+  for name in $(services); do
+    unit_installed "$name" || continue
+    any=1
+    unit_name="$(unit_name_for "$name")"
+    state="$(systemctl --user is-active "$unit_name" 2>/dev/null || true)"
+    if [[ "$state" == active ]]; then
+      ok "$name"
+    else
+      err "$name is ${state:-unknown}"
+    fi
+  done
+  (( any )) || info "No services enabled on this machine yet. See: $PROGRAM list"
+  return 0
+}
+
+cmd_relink() {
+  local name unit_path unit_name changed=() unmanaged=() refreshed=0
+  for name in $(services); do
+    unit_path="$(unit_path_for "$name")" || continue
+    unit_name="$(basename "$unit_path")"
+
+    if [[ -e "$UNIT_DIR/$unit_name" && ! -L "$UNIT_DIR/$unit_name" ]]; then
+      unmanaged+=("$name")
+      continue
+    fi
+    unit_installed "$name" || continue
+
+    link_file "$unit_path" "$UNIT_DIR/$unit_name"
+    mkdir -p "$TARGET_DIR/$name"
+    link_file "$SERVER_DIR/$name/compose.yml" "$TARGET_DIR/$name/compose.yml"
+    refreshed=$((refreshed + 1))
+
+    # Changed since the last time this machine looked, which is what makes a
+    # pull actionable: the restart is deliberately yours to run, so the least
+    # this can do is say which services are running a definition that is no
+    # longer what the repository says.
+    local now
+    now="$(definition_hash "$name")"
+    if [[ "$(recorded_hash "$name")" != "$now" ]]; then
+      changed+=("$name")
+      record_hash "$name" "$now"
+    fi
+  done
+
+  systemctl --user daemon-reload 2>/dev/null || true
+  info "Relinked $refreshed enabled service(s)"
+  if (( ${#unmanaged[@]} > 0 )); then
+    warn "Installed by hand, left alone: ${unmanaged[*]}"
+  fi
+  if (( ${#changed[@]} > 0 )); then
+    warn "Definitions changed; restart each when ready:"
+    for name in "${changed[@]}"; do
+      printf '    %s:  systemctl --user restart %s\n' "$name" "$(unit_name_for "$name")"
+    done
+  fi
+}
+
+# ── Dispatcher ───────────────────────────────────────────────────────────────
+
+main() {
+  if [[ ! -d "$SERVER_DIR" ]]; then
+    err "No service catalog at $SERVER_DIR"
+    exit 1
+  fi
+  local cmd="${1:-}"
+  case "$cmd" in
+    list)    shift; cmd_list "$@" ;;
+    enable)  shift; cmd_enable "$@" ;;
+    disable) shift; cmd_disable "$@" ;;
+    status)  shift; cmd_status "$@" ;;
+    relink)  shift; cmd_relink "$@" ;;
+    help|-h|--help|"") usage ;;
+    *)
+      err "Unknown command: '$cmd'"
+      echo
+      usage
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+# pkexec, with a stated reason on the password prompt.
+#
+#   panama-sudo --reason "Installing gamemode hooks" -- dnf install gamemode
+#
+# The reason travels to the shell over Quickshell IPC before pkexec runs, and
+# Panama's prompt shows it clearly labeled beside polkitd's own action message
+# -- beside, never instead of: anything can claim any reason, so the real
+# action text stays the trust anchor. Meant for agents and scripts, so the
+# person at the keyboard learns WHY before typing their password.
+#
+# Degrades to plain pkexec: no --reason, no running shell, or no qs on PATH
+# all behave identically to calling pkexec yourself.
+
+set -euo pipefail
+
+reason=""
+if [[ "${1:-}" == "--reason" ]]; then
+  reason="${2:?panama-sudo: --reason needs a value}"
+  shift 2
+fi
+[[ "${1:-}" == "--" ]] && shift
+
+if (( $# == 0 )); then
+  echo 'usage: panama-sudo [--reason "why"] -- command [args...]' >&2
+  exit 2
+fi
+
+if [[ -n "$reason" ]] && command -v qs >/dev/null 2>&1; then
+  qs ipc call polkit reason "$reason" >/dev/null 2>&1 || true
+fi
+
+exec pkexec "$@"
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+
+# Make a video smaller, or turn a picture into another format.
+#
+#   panama-transcode video <file> 1080p|720p|480p
+#   panama-transcode image <file> jpg|png|webp
+#
+# The two things people actually right-click a media file to do. macOS has
+# Quick Actions for both; Linux file managers have neither, and the usual
+# answer is a web uploader or a forgotten ffmpeg incantation.
+#
+# Two rules, both about not losing work:
+#
+#   * The input is never written to. Output goes beside it with a suffix.
+#   * An existing output is never overwritten. The suffix gains a number
+#     rather than replacing something somebody made earlier.
+#
+# ffmpeg does the work and is already a declared dependency; this only decides
+# the arguments, which is the part worth writing down once.
+
+set -uo pipefail
+
+err() { printf 'panama-transcode: %s\n' "$*" >&2; }
+
+command -v ffmpeg >/dev/null 2>&1 || { err 'ffmpeg is not installed'; exit 1; }
+
+# A path that does not exist yet, beside the input.
+free_path() {
+    local dir="$1" stem="$2" suffix="$3" ext="$4"
+    local candidate="$dir/$stem-$suffix.$ext"
+    local counter=2
+    while [[ -e "$candidate" ]]; do
+        candidate="$dir/$stem-$suffix-$counter.$ext"
+        counter=$(( counter + 1 ))
+    done
+    printf '%s' "$candidate"
+}
+
+notify() {
+    command -v notify-send >/dev/null 2>&1 || return 0
+    notify-send --icon="${3:-video-x-generic}" "$1" "$2" 2>/dev/null || true
+}
+
+cmd_video() {
+    local input="${1:-}" preset="${2:-1080p}"
+    [[ -f "$input" ]] || { err 'that file does not exist'; return 2; }
+
+    local height
+    case "$preset" in
+        1080p) height=1080 ;;
+        720p)  height=720 ;;
+        480p)  height=480 ;;
+        *)     err "unknown size: $preset"; return 2 ;;
+    esac
+
+    local dir stem output
+    dir="$(dirname "$input")"
+    stem="$(basename "${input%.*}")"
+    output="$(free_path "$dir" "$stem" "$preset" mp4)"
+
+    notify "Transcoding" "$(basename "$input") → $preset" video-x-generic
+    # -2 rather than -1 on width: H.264 needs even dimensions, and an odd one
+    # fails at the very end of a long encode.
+    if ffmpeg -nostdin -loglevel error -i "$input" \
+        -vf "scale=-2:'min($height,ih)'" \
+        -c:v libx264 -crf 23 -preset medium \
+        -c:a aac -b:a 128k \
+        "$output" </dev/null; then
+        notify "Transcoded" "$(basename "$output")" video-x-generic
+        printf '%s\n' "$output"
+    else
+        rm -f "$output"
+        notify "Transcode failed" "$(basename "$input")" dialog-error-symbolic
+        return 1
+    fi
+}
+
+cmd_image() {
+    local input="${1:-}" format="${2:-jpg}"
+    [[ -f "$input" ]] || { err 'that file does not exist'; return 2; }
+
+    case "$format" in
+        jpg|png|webp) ;;
+        *) err "unknown format: $format"; return 2 ;;
+    esac
+
+    local dir stem output
+    dir="$(dirname "$input")"
+    stem="$(basename "${input%.*}")"
+    output="$(free_path "$dir" "$stem" converted "$format")"
+
+    local -a quality=()
+    [[ "$format" == "jpg" ]] && quality=(-q:v 3)
+    [[ "$format" == "webp" ]] && quality=(-quality 82)
+
+    if ffmpeg -nostdin -loglevel error -i "$input" "${quality[@]}" "$output" </dev/null; then
+        notify "Converted" "$(basename "$output")" image-x-generic
+        printf '%s\n' "$output"
+    else
+        rm -f "$output"
+        notify "Conversion failed" "$(basename "$input")" dialog-error-symbolic
+        return 1
+    fi
+}
+
+case "${1:-}" in
+    video) shift; cmd_video "$@" ;;
+    image) shift; cmd_image "$@" ;;
+    -h|--help|"")
+        cat <<'USAGE'
+usage: panama-transcode video <file> [1080p|720p|480p]
+       panama-transcode image <file> [jpg|png|webp]
+
+Writes beside the input, never over it, and never over an existing output.
+USAGE
+        ;;
+    *) err "unknown command: $1"; exit 2 ;;
+esac
@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+
+# A website, as an application.
+#
+#   panama-webapp install https://app.example.com "Example"
+#   panama-webapp list
+#   panama-webapp remove "Example"
+#
+# Both macOS and Windows ship this now -- Safari's "Add to Dock", Edge's
+# "Install this site as an app" -- and the dock and launcher here had nothing
+# to feed them but installed packages. A web app gets its own icon, its own
+# window with no browser chrome, and its own entry in the launcher, which is
+# most of what "installed" means in practice.
+#
+# The desktop entry is ordinary and inspectable: it lives in
+# ~/.local/share/applications with everything else, and `remove` finds its own
+# entries by the launcher line rather than by keeping a list somewhere.
+#
+# Chromium-family browsers implement --app. Firefox does not, and there is no
+# honest equivalent, so a machine whose default browser is Firefox is told
+# rather than given something that opens a normal window and pretends.
+
+set -uo pipefail
+
+APPLICATIONS="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
+ICONS="${XDG_DATA_HOME:-$HOME/.local/share}/icons/hicolor/256x256/apps"
+LAUNCH_MARKER="panama-webapp"
+
+err() { printf 'panama-webapp: %s\n' "$*" >&2; }
+
+# A filename that cannot escape the applications directory. Everything that is
+# not a letter or a digit becomes a hyphen, which also makes the result
+# predictable enough for `remove` to find.
+slugify() {
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
+}
+
+# The browser to open the app window with. Follows the desktop's own default
+# rather than naming one, and refuses rather than degrading when that browser
+# cannot do app mode.
+resolve_browser() {
+    local desktop exec_line binary
+    desktop="$(xdg-settings get default-web-browser 2>/dev/null || true)"
+
+    if [[ -n "$desktop" ]]; then
+        local file
+        for dir in "$APPLICATIONS" /usr/local/share/applications /usr/share/applications; do
+            file="$dir/$desktop"
+            [[ -r "$file" ]] || continue
+            exec_line="$(sed -n 's/^Exec=//p' "$file" | head -1)"
+            binary="$(awk '{ print $1 }' <<<"$exec_line")"
+            break
+        done
+    fi
+
+    [[ -n "${binary:-}" ]] || binary="$(command -v chromium || command -v google-chrome || true)"
+    [[ -n "$binary" ]] || return 1
+
+    # Chromium-family only. The name check is crude but the alternative is
+    # launching a browser to ask it, which is worse.
+    case "$(basename "$binary")" in
+        *firefox*|*librewolf*|*zen*) return 2 ;;
+    esac
+    printf '%s' "$binary"
+}
+
+# Four attempts, in descending order of how much the site had to say about it.
+# An icon is never worth failing an install over: a web app with the generic
+# icon still works.
+fetch_icon() {
+    local url="$1" slug="$2" origin html href target
+    origin="$(sed -E 's#^(https?://[^/]+).*#\1#' <<<"$url")"
+    target="$ICONS/$slug.png"
+    mkdir -p "$ICONS"
+
+    html="$(curl -fsSL --max-time 10 "$url" 2>/dev/null || true)"
+    href="$(grep -oiE '<link[^>]+rel="[^"]*apple-touch-icon[^"]*"[^>]*>' <<<"$html" \
+        | grep -oiE 'href="[^"]+"' | head -1 | sed 's/href="//I; s/"$//' || true)"
+
+    if [[ -n "$href" ]]; then
+        case "$href" in
+            http*) ;;
+            /*)    href="$origin$href" ;;
+            *)     href="$origin/$href" ;;
+        esac
+        curl -fsSL --max-time 10 -o "$target" "$href" 2>/dev/null && { printf '%s' "$slug"; return 0; }
+    fi
+
+    curl -fsSL --max-time 10 -o "$target" "$origin/apple-touch-icon.png" 2>/dev/null \
+        && { printf '%s' "$slug"; return 0; }
+
+    local host
+    host="$(sed -E 's#^https?://([^/]+).*#\1#' <<<"$url")"
+    curl -fsSL --max-time 10 -o "$target" \
+        "https://www.google.com/s2/favicons?sz=256&domain=$host" 2>/dev/null \
+        && { printf '%s' "$slug"; return 0; }
+
+    rm -f "$target"
+    printf 'applications-internet'
+}
+
+cmd_install() {
+    local url="${1:-}" name="${2:-}"
+    [[ -n "$url" ]] || { err 'install needs a URL'; return 2; }
+    [[ "$url" =~ ^https?:// ]] || { err 'the URL must begin with http:// or https://'; return 2; }
+
+    # Default the name from the host, so `install https://app.example.com` is
+    # enough for the common case.
+    [[ -n "$name" ]] || name="$(sed -E 's#^https?://(www\.)?([^/]+).*#\2#' <<<"$url")"
+
+    local slug; slug="$(slugify "$name")"
+    [[ -n "$slug" ]] || { err 'that name has no usable characters in it'; return 2; }
+
+    local browser status
+    browser="$(resolve_browser)"; status=$?
+    if (( status == 2 )); then
+        err 'the default browser cannot open a site as its own application.'
+        err 'Chromium-family browsers implement --app; Firefox does not.'
+        return 1
+    fi
+    [[ -n "$browser" ]] || { err 'no browser found'; return 1; }
+
+    local icon; icon="$(fetch_icon "$url" "$slug")"
+
+    mkdir -p "$APPLICATIONS"
+    local entry="$APPLICATIONS/$LAUNCH_MARKER-$slug.desktop"
+    cat >"$entry" <<ENTRY
+[Desktop Entry]
+Type=Application
+Name=$name
+Comment=$url
+Exec=$browser --app=$url
+Icon=$icon
+Terminal=false
+Categories=Network;
+StartupWMClass=$browser
+X-Panama-WebApp=$url
+ENTRY
+
+    command -v update-desktop-database >/dev/null 2>&1 \
+        && update-desktop-database "$APPLICATIONS" >/dev/null 2>&1
+    command -v gtk-update-icon-cache >/dev/null 2>&1 \
+        && gtk-update-icon-cache -f -t "${XDG_DATA_HOME:-$HOME/.local/share}/icons/hicolor" 2>/dev/null
+
+    printf 'Installed %s\n' "$name"
+    printf '  %s\n' "$entry"
+}
+
+cmd_list() {
+    local entry name url
+    shopt -s nullglob
+    for entry in "$APPLICATIONS/$LAUNCH_MARKER-"*.desktop; do
+        name="$(sed -n 's/^Name=//p' "$entry" | head -1)"
+        url="$(sed -n 's/^X-Panama-WebApp=//p' "$entry" | head -1)"
+        printf '%s\t%s\n' "$name" "$url"
+    done
+}
+
+cmd_remove() {
+    local name="${1:-}"
+    [[ -n "$name" ]] || { err 'remove needs a name'; return 2; }
+    local slug; slug="$(slugify "$name")"
+    local entry="$APPLICATIONS/$LAUNCH_MARKER-$slug.desktop"
+
+    # Only ever removes an entry this command installed. The prefix and the
+    # X-Panama-WebApp key both have to be there, so a name collision with a
+    # real application cannot delete it.
+    [[ -f "$entry" ]] || { err "no web app named '$name'"; return 1; }
+    grep -q '^X-Panama-WebApp=' "$entry" || { err "$entry is not a Panama web app"; return 1; }
+
+    rm -f "$entry" "$ICONS/$slug.png"
+    command -v update-desktop-database >/dev/null 2>&1 \
+        && update-desktop-database "$APPLICATIONS" >/dev/null 2>&1
+    printf 'Removed %s\n' "$name"
+}
+
+case "${1:-}" in
+    install) shift; cmd_install "$@" ;;
+    list)    shift; cmd_list "$@" ;;
+    remove)  shift; cmd_remove "$@" ;;
+    -h|--help|"")
+        cat <<'USAGE'
+usage: panama-webapp install <url> [name]
+       panama-webapp list
+       panama-webapp remove <name>
+
+Turns a website into an application: its own icon, its own window with no
+browser chrome, and its own entry in the launcher.
+USAGE
+        ;;
+    *) err "unknown command: $1"; exit 2 ;;
+esac
@@ -0,0 +1,589 @@
+#!/usr/bin/env bash
+
+# Panama's front door: the one command a fresh Fedora machine needs.
+#
+# Download this file from the documented commit URL, verify its documented
+# SHA-256, then pass both immutable values as PANAMA_BOOT_REVISION and
+# PANAMA_BOOT_SHA256 when invoking it.
+#
+# Deliberately dumb, because a copy of this script leaves the repository the
+# moment somebody curls it -- nothing here can be fixed by re-running
+# ./install, so there is as little here as possible: get git, get the clone,
+# hand off. Everything with judgment in it lives in `install`, which is also
+# where re-runs and upgrades already work.
+#
+# The one exception to dumb is the root path below, which cannot live in
+# `install`: a fresh VPS hands you a root login and nothing else, and the user
+# that `install` needs to exist is exactly what has not been created yet.
+
+set -euo pipefail
+
+if [[ ! "${PANAMA_BOOT_REVISION:-}" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "boot: PANAMA_BOOT_REVISION must be a full lowercase commit" >&2
+  exit 1
+fi
+if [[ ! "${PANAMA_BOOT_SHA256:-}" =~ ^[0-9a-f]{64}$ ]]; then
+  echo "boot: PANAMA_BOOT_SHA256 must be a lowercase SHA-256" >&2
+  exit 1
+fi
+actual_boot_sha="$(sha256sum "${BASH_SOURCE[0]}" | cut -d' ' -f1)"
+if [[ "$actual_boot_sha" != "$PANAMA_BOOT_SHA256" ]]; then
+  echo "boot: downloaded boot file does not match PANAMA_BOOT_SHA256" >&2
+  exit 1
+fi
+
+REPO_URL="https://git.gbrown.org/gib/Panama.git"
+PANAMA_PATH="${PANAMA_PATH:-$HOME/.local/share/Panama}"
+export PANAMA_PATH
+BOOTSTRAP_USER=""
+
+checkout_command() {
+  if [[ -n "$BOOTSTRAP_USER" ]]; then
+    runuser -u "$BOOTSTRAP_USER" -- "$@"
+  else
+    "$@"
+  fi
+}
+
+# Git's index hints are performance promises, not trust evidence. In
+# particular, assume-unchanged and skip-worktree can make porcelain status
+# report a clean checkout whose files no longer match HEAD. Compare every
+# tracked blob and Git mode with the verified commit before handing control to
+# any file in the worktree.
+checkout_matches_verified_commit() (
+  local checkout="$1" listing="" entry metadata mode type expected path actual
+  local link_target_with_sentinel link_target
+
+  trap '[[ -z "$listing" ]] || rm -f -- "$listing"' EXIT
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+  listing="$(mktemp -u -t panama-boot-tree.XXXXXX)" || exit 1
+  umask 077
+  if ! (set -o noclobber; : >"$listing") 2>/dev/null; then
+    listing=""
+    exit 1
+  fi
+
+  checkout_command git -C "$checkout" ls-tree -rz --full-tree \
+    "$PANAMA_BOOT_REVISION" >"$listing" || exit 1
+  while IFS= read -r -d '' entry; do
+    [[ "$entry" == *$'\t'* ]] || exit 1
+    metadata="${entry%%$'\t'*}"
+    path="${entry#*$'\t'}"
+    read -r mode type expected <<<"$metadata"
+    [[ "$type" == blob && -n "$path" && "$path" != /* ]] || exit 1
+
+    case "$mode" in
+      100644) [[ -f "$checkout/$path" && ! -L "$checkout/$path" \
+        && ! -x "$checkout/$path" ]] || exit 1 ;;
+      100755) [[ -f "$checkout/$path" && ! -L "$checkout/$path" \
+        && -x "$checkout/$path" ]] || exit 1 ;;
+      120000)
+        [[ -L "$checkout/$path" ]] || exit 1
+        # hash-object given a pathname follows a symlink. Git's 120000 blob is
+        # the link text itself, including any trailing newlines, so preserve
+        # those bytes with a sentinel and hash stdin instead.
+        link_target_with_sentinel="$(
+          readlink -n -- "$checkout/$path" && printf .
+        )" || exit 1
+        [[ "$link_target_with_sentinel" == *. ]] || exit 1
+        link_target="${link_target_with_sentinel%.}"
+        actual="$(
+          printf '%s' "$link_target" \
+            | checkout_command git -C "$checkout" hash-object --stdin
+        )" || exit 1
+        [[ "$actual" == "$expected" ]] || exit 1
+        continue
+        ;;
+      *) exit 1 ;;
+    esac
+
+    actual="$(checkout_command git -C "$checkout" hash-object --no-filters -- "$path")" \
+      || exit 1
+    [[ "$actual" == "$expected" ]] || exit 1
+  done <"$listing"
+)
+
+prepare_panama_checkout() {
+  local checkout="$1" actual_head checkout_status
+
+  if [[ -e "$checkout" && ! -d "$checkout/.git" ]]; then
+    printf 'boot: %s exists but is not a Panama Git checkout\n' "$checkout" >&2
+    return 1
+  fi
+
+  if [[ -d "$checkout/.git" ]]; then
+    checkout_status="$(checkout_command git -C "$checkout" status --porcelain)" || {
+      printf 'boot: could not inspect the existing checkout at %s\n' "$checkout" >&2
+      return 1
+    }
+    if [[ -n "$checkout_status" ]]; then
+      printf 'boot: existing checkout at %s has local changes\n' "$checkout" >&2
+      return 1
+    fi
+
+    echo "Panama is already cloned at $checkout; fetching the verified revision"
+    checkout_command git -C "$checkout" fetch origin "$PANAMA_BOOT_REVISION" || return 1
+    if ! checkout_command git -C "$checkout" merge-base --is-ancestor \
+      HEAD "$PANAMA_BOOT_REVISION"; then
+      echo "boot: existing checkout cannot fast-forward to the verified revision" >&2
+      return 1
+    fi
+    checkout_command git -C "$checkout" merge --ff-only "$PANAMA_BOOT_REVISION" || return 1
+  else
+    checkout_command mkdir -p "$(dirname "$checkout")" || return 1
+    checkout_command git init "$checkout" || return 1
+    checkout_command git -C "$checkout" remote add origin "$REPO_URL" || return 1
+    checkout_command git -C "$checkout" fetch --depth=1 origin \
+      "$PANAMA_BOOT_REVISION" || return 1
+    checkout_command git -C "$checkout" checkout --detach \
+      "$PANAMA_BOOT_REVISION" || return 1
+
+    actual_head="$(checkout_command git -C "$checkout" rev-parse 'HEAD^{commit}')" || return 1
+    if [[ "$actual_head" != "$PANAMA_BOOT_REVISION" ]]; then
+      echo "boot: fetched checkout does not match PANAMA_BOOT_REVISION" >&2
+      return 1
+    fi
+
+    checkout_command git -C "$checkout" checkout -b main || return 1
+    checkout_command git -C "$checkout" config branch.main.remote origin || return 1
+    checkout_command git -C "$checkout" config branch.main.merge refs/heads/main || return 1
+  fi
+
+  actual_head="$(checkout_command git -C "$checkout" rev-parse 'HEAD^{commit}')" || return 1
+  if [[ "$actual_head" != "$PANAMA_BOOT_REVISION" ]]; then
+    echo "boot: checkout HEAD does not match PANAMA_BOOT_REVISION" >&2
+    return 1
+  fi
+}
+
+SERVER=0
+INSTALL_ARGS=()
+for arg in "$@"; do
+  case "$arg" in
+    --server) SERVER=1; INSTALL_ARGS+=(--server) ;;
+    *)
+      printf 'boot: unknown argument: %s\n' "$arg" >&2
+      printf 'usage: boot [--server]\n' >&2
+      exit 2 ;;
+  esac
+done
+
+# Keep the worktree comparison at the last possible boundary. Checkout
+# preparation may invoke several commands and return to the caller; performing
+# the byte/mode/link check here ensures a change in that interval is rejected
+# before any tracked file is executed.
+verified_install_handoff() {
+  local use_tty="$1"
+  if ! checkout_matches_verified_commit "$PANAMA_PATH"; then
+    echo "boot: checkout files do not match PANAMA_BOOT_REVISION" >&2
+    return 1
+  fi
+  if [[ -n "$BOOTSTRAP_USER" ]]; then
+    if (( use_tty )); then
+      exec runuser -u "$BOOTSTRAP_USER" -- env PANAMA_PATH="$PANAMA_PATH" \
+        "$PANAMA_PATH/install" ${INSTALL_ARGS[@]+"${INSTALL_ARGS[@]}"} </dev/tty
+    fi
+    exec runuser -u "$BOOTSTRAP_USER" -- env PANAMA_PATH="$PANAMA_PATH" \
+      "$PANAMA_PATH/install" ${INSTALL_ARGS[@]+"${INSTALL_ARGS[@]}"}
+  fi
+  if (( use_tty )); then
+    exec "$PANAMA_PATH/install" ${INSTALL_ARGS[@]+"${INSTALL_ARGS[@]}"} </dev/tty
+  fi
+  exec "$PANAMA_PATH/install" ${INSTALL_ARGS[@]+"${INSTALL_ARGS[@]}"}
+}
+
+# The public bootstrap contract runs this branch as an ordinary user with a
+# stubbed root identity. Keep its filesystem adapter unavailable to a real root
+# shell so it cannot redirect a real installation by accident.
+BOOT_ROOT="${PANAMA_BOOT_FIXTURE_ROOT:-}"
+if [[ -n "$BOOT_ROOT" && "$EUID" -eq 0 ]]; then
+  echo "boot: PANAMA_BOOT_FIXTURE_ROOT is test-only" >&2
+  exit 1
+fi
+
+system_path() {
+  local path="$1"
+  [[ "$path" == /* ]] || return 2
+  printf '%s%s\n' "$BOOT_ROOT" "$path"
+}
+
+valid_authorized_keys() {
+  local keys="$1" line saw_key=0
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if [[ "$line" =~ ^[[:space:]]*$ || "$line" =~ ^[[:space:]]*# ]]; then
+      continue
+    fi
+    if ! ssh-keygen -l -f /dev/stdin >/dev/null 2>&1 <<<"$line"; then
+      return 1
+    fi
+    saw_key=1
+  done <"$keys"
+  (( saw_key ))
+}
+
+safe_authorized_keys() {
+  local username="$1" user_home="$2" uid ssh_dir keys
+  uid="$(id -u "$username")" || return 1
+  [[ "$uid" =~ ^[0-9]+$ && "$uid" != 0 && "$user_home" == /* ]] || return 1
+  ssh_dir="$user_home/.ssh"
+  keys="$ssh_dir/authorized_keys"
+  [[ -d "$ssh_dir" && ! -L "$ssh_dir" && -f "$keys" && ! -L "$keys" ]] || return 1
+  [[ "$(stat -Lc '%u:%a' "$ssh_dir")" == "$uid:700" ]] || return 1
+  [[ "$(stat -Lc '%u:%a' "$keys")" == "$uid:600" ]] || return 1
+  valid_authorized_keys "$keys"
+}
+
+safe_root_authorized_keys() {
+  local keys
+  keys="$(system_path /root/.ssh/authorized_keys)" || return 1
+  [[ -f "$keys" && ! -L "$keys" ]] || return 1
+  [[ "$(stat -Lc '%u:%a' "$keys")" == '0:600' ]] || return 1
+  valid_authorized_keys "$keys"
+}
+
+detect_ssh_unit() {
+  local unit
+  for unit in sshd.service ssh.service; do
+    systemctl cat "$unit" >/dev/null 2>&1 && {
+      printf '%s\n' "$unit"
+      return 0
+    }
+  done
+  return 1
+}
+
+restore_ssh_dropin() {
+  local restore
+  if (( ssh_had_prior )); then
+    [[ -n "$ssh_backup" && -f "$ssh_backup" && ! -L "$ssh_backup" ]] || return 1
+    restore="$(mktemp --tmpdir="$sshd_dir" .00-panama.XXXXXX.restore)" || return 1
+    if ! cp -a -- "$ssh_backup" "$restore"; then
+      remove_ssh_artifact "$restore" || true
+      return 1
+    fi
+    if ! mv -f -- "$restore" "$ssh_dropin"; then
+      remove_ssh_artifact "$restore" || true
+      return 1
+    fi
+  else
+    remove_ssh_artifact "$ssh_dropin"
+  fi
+}
+
+restore_ssh_transaction_traps() {
+  trap - EXIT INT TERM
+  [[ -n "${ssh_saved_exit_trap:-}" ]] && eval "$ssh_saved_exit_trap"
+  [[ -n "${ssh_saved_int_trap:-}" ]] && eval "$ssh_saved_int_trap"
+  [[ -n "${ssh_saved_term_trap:-}" ]] && eval "$ssh_saved_term_trap"
+  return 0
+}
+
+remove_ssh_artifact() {
+  local artifact="$1"
+  [[ -n "$artifact" && ( -e "$artifact" || -L "$artifact" ) ]] || return 0
+  if rm -f -- "$artifact"; then
+    return 0
+  fi
+  printf 'SSH transaction cleanup failed. Retained artifact: %s\n' "$artifact" >&2
+  printf '  rm -f -- %q\n' "$artifact" >&2
+  return 1
+}
+
+print_ssh_recovery() {
+  if (( ssh_had_prior )); then
+    printf 'SSH rollback needs manual recovery. Backup: %s\n' "$ssh_backup" >&2
+    printf '  cp -a -- %q %q\n' "$ssh_backup" "$ssh_dropin" >&2
+  else
+    printf 'SSH rollback needs manual recovery. No prior drop-in existed.\n' >&2
+    printf '  rm -f -- %q\n' "$ssh_dropin" >&2
+  fi
+  printf '  sshd -t\n' >&2
+  printf '  systemctl reload %s\n' "$ssh_unit" >&2
+}
+
+policy_is_no() {
+  local policy="$1" setting="$2"
+  awk -v setting="$setting" '
+    $1 == setting { count += 1; if ($2 != "no") bad = 1 }
+    END { exit count != 1 || bad }
+  ' <<<"$policy"
+}
+
+effective_ssh_policy_is_hardened() {
+  local username="$1" root_policy target_policy context
+  context='host=localhost,addr=127.0.0.1'
+  root_policy="$(sshd -T -C "user=root,$context")" || return 1
+  policy_is_no "$root_policy" permitrootlogin || return 1
+  policy_is_no "$root_policy" passwordauthentication || return 1
+  policy_is_no "$root_policy" kbdinteractiveauthentication || return 1
+
+  target_policy="$(sshd -T -C "user=$username,$context")" || return 1
+  policy_is_no "$target_policy" passwordauthentication || return 1
+  policy_is_no "$target_policy" kbdinteractiveauthentication
+}
+
+rollback_ssh_transaction() {
+  local reload_restored="$1" rollback_failed=0
+  restore_ssh_dropin || rollback_failed=1
+  sshd -t || rollback_failed=1
+  if (( reload_restored )); then
+    systemctl reload "$ssh_unit" || rollback_failed=1
+  fi
+  ssh_transaction_state=""
+  restore_ssh_transaction_traps
+  if (( rollback_failed )); then
+    print_ssh_recovery
+  else
+    remove_ssh_artifact "$ssh_backup" || true
+  fi
+  return 1
+}
+
+handle_ssh_transaction_exit() {
+  if [[ "$ssh_transaction_state" == preparing \
+    || ( "$ssh_transaction_state" == activating && -e "$ssh_candidate" ) ]]; then
+    remove_ssh_artifact "$ssh_candidate" || true
+    remove_ssh_artifact "$ssh_backup" || true
+  elif [[ "$ssh_transaction_state" == activating || "$ssh_transaction_state" == activated ]]; then
+    restore_ssh_dropin || true
+  fi
+}
+
+handle_ssh_transaction_signal() {
+  local signal_status="$1"
+  trap - INT TERM
+  if [[ "$ssh_transaction_state" == preparing \
+    || ( "$ssh_transaction_state" == activating && -e "$ssh_candidate" ) ]]; then
+    ssh_transaction_state=""
+    restore_ssh_transaction_traps
+    remove_ssh_artifact "$ssh_candidate" || true
+    remove_ssh_artifact "$ssh_backup" || true
+  else
+    rollback_ssh_transaction 1 || true
+  fi
+  exit "$signal_status"
+}
+
+harden_server_ssh() {
+  local username="$1" user_home="$2" sshd_dir ssh_dropin harden ssh_unit
+  local ssh_candidate="" ssh_backup="" ssh_had_prior=0
+  local ssh_transaction_state=""
+  local ssh_saved_exit_trap ssh_saved_int_trap ssh_saved_term_trap
+  sshd_dir="$(system_path /etc/ssh/sshd_config.d)" || return 1
+  ssh_dropin="$sshd_dir/00-panama.conf"
+
+  if [[ -L "$ssh_dropin" || ( -e "$ssh_dropin" && ! -f "$ssh_dropin" ) ]]; then
+    printf 'SSH hardening unavailable: %s is not a regular file\n' "$ssh_dropin" >&2
+    return 2
+  fi
+
+  if ! ssh_unit="$(detect_ssh_unit)"; then
+    echo "SSH hardening unavailable: neither sshd.service nor ssh.service is installed" >&2
+    return 2
+  fi
+
+  printf 'Harden sshd (disable root, password, and keyboard-interactive authentication)? [Y/n]: '
+  read -r harden </dev/tty || harden=""
+  if [[ "$harden" =~ ^[Nn] ]]; then
+    return 0
+  fi
+
+  ssh_saved_exit_trap="$(trap -p EXIT)"
+  ssh_saved_int_trap="$(trap -p INT)"
+  ssh_saved_term_trap="$(trap -p TERM)"
+  ssh_transaction_state=preparing
+  trap 'handle_ssh_transaction_exit' EXIT
+  trap 'handle_ssh_transaction_signal 130' INT
+  trap 'handle_ssh_transaction_signal 143' TERM
+
+  if ! ssh_candidate="$(umask 077; mktemp --tmpdir="$sshd_dir" .00-panama.XXXXXX.tmp)"; then
+    ssh_transaction_state=""
+    restore_ssh_transaction_traps
+    return 1
+  fi
+  if ! printf 'PermitRootLogin no\nPasswordAuthentication no\nKbdInteractiveAuthentication no\n' >"$ssh_candidate"; then
+    ssh_transaction_state=""
+    restore_ssh_transaction_traps
+    remove_ssh_artifact "$ssh_candidate" || true
+    return 1
+  fi
+
+  if [[ -e "$ssh_dropin" ]]; then
+    ssh_had_prior=1
+    if ! ssh_backup="$(umask 077; mktemp --tmpdir="$sshd_dir" .00-panama.XXXXXX.backup)"; then
+      ssh_transaction_state=""
+      restore_ssh_transaction_traps
+      remove_ssh_artifact "$ssh_candidate" || true
+      return 1
+    fi
+    if ! cp -a -- "$ssh_dropin" "$ssh_backup"; then
+      ssh_transaction_state=""
+      restore_ssh_transaction_traps
+      remove_ssh_artifact "$ssh_candidate" || true
+      remove_ssh_artifact "$ssh_backup" || true
+      return 1
+    fi
+  fi
+
+  ssh_transaction_state=activating
+  if ! mv -f -- "$ssh_candidate" "$ssh_dropin"; then
+    ssh_transaction_state=""
+    restore_ssh_transaction_traps
+    remove_ssh_artifact "$ssh_candidate" || true
+    remove_ssh_artifact "$ssh_backup" || true
+    return 1
+  fi
+  ssh_candidate=""
+  ssh_transaction_state=activated
+
+  if ! sshd -t || ! effective_ssh_policy_is_hardened "$username"; then
+    rollback_ssh_transaction 0 || true
+    return 1
+  fi
+
+  if ! systemctl reload "$ssh_unit"; then
+    rollback_ssh_transaction 1 || true
+    return 1
+  fi
+
+  ssh_transaction_state=""
+  restore_ssh_transaction_traps
+  remove_ssh_artifact "$ssh_backup" || return 1
+  echo "Wrote $ssh_dropin; make sure your key works before logging out."
+}
+
+# Panama assumes Fedora's repositories and package names.
+if ! grep -qi '^ID=fedora' /etc/os-release 2>/dev/null; then
+  echo "This looks like something other than Fedora; Panama only supports Fedora." >&2
+  exit 1
+fi
+
+# ── Root ─────────────────────────────────────────────────────────────────────
+#
+# On a desktop, root is a mistake: the clone and every dotfile would land in
+# root's home and configure the wrong user. On a fresh VPS it is the starting
+# condition -- Hetzner hands over a root login and nothing else -- so with
+# --server this walks the machine from that to a normal Panama install: a
+# user with sudo, keys, an optionally hardened sshd, and `install --server`
+# running as that user. Every step checks before acting, because the machine
+# may be anywhere along this path already: a user half-created by hand, keys
+# already copied, sshd already locked down.
+if [[ "$(id -u)" -eq 0 ]]; then
+  if (( ! SERVER )); then
+    echo "Run this as your own user, not root: the install configures YOUR desktop." >&2
+    echo "Setting up a fresh server from its root login is: boot --server" >&2
+    exit 1
+  fi
+
+  # Everything here asks, and a root shell from `bash <(curl ...)` can have
+  # the pipe as stdin, so every prompt reads the terminal explicitly.
+  if ! (exec </dev/tty) 2>/dev/null; then
+    echo "No terminal to ask on; run this from an interactive root shell." >&2
+    exit 1
+  fi
+
+  printf 'Username for this server [gib]: '
+  read -r username </dev/tty || username=""
+  username="${username:-gib}"
+
+  if id -u "$username" >/dev/null 2>&1; then
+    echo "User $username already exists"
+    # wheel is what makes sudo work on Fedora; a user created by hand may not
+    # have it, and everything after this depends on it.
+    id -nG "$username" | grep -qw wheel || usermod -aG wheel "$username"
+  else
+    echo "Creating $username with sudo (wheel)"
+    useradd -m -G wheel "$username"
+  fi
+
+  # useradd leaves the account locked, and sudo asks for this password -- a
+  # user who cannot sudo is a user the install cannot run as.
+  if ! passwd -S "$username" 2>/dev/null | awk '{exit $2 != "PS" && $2 != "P"}'; then
+    echo "Set a password for $username (sudo will ask for it):"
+    passwd "$username" </dev/tty
+  fi
+
+  # Do not close root/password access until the account's key is an exact,
+  # usable login path. The fixture adapter resolves these logical system paths
+  # beneath a temporary root; ordinary execution receives the original paths.
+  logical_user_home="$(getent passwd "$username" | cut -d: -f6)"
+  user_home=""
+  if [[ "$logical_user_home" == /* ]]; then
+    user_home="$(system_path "$logical_user_home")" || true
+  fi
+  bootstrap_home="$user_home"
+  if [[ -z "$bootstrap_home" ]]; then
+    bootstrap_home="$(system_path "/home/$username")"
+  fi
+
+  user_ssh_dir="$user_home/.ssh"
+  user_keys="$user_ssh_dir/authorized_keys"
+  if [[ -n "$user_home" && ! -e "$user_keys" && ! -L "$user_keys" \
+    && ! -L "$user_ssh_dir" ]] && safe_root_authorized_keys; then
+    copy_root_key=0
+    if [[ ! -e "$user_ssh_dir" ]]; then
+      copy_root_key=1
+    elif [[ ! -d "$user_ssh_dir" \
+      || "$(stat -Lc '%u:%a' "$user_ssh_dir")" != "$(id -u "$username"):700" ]]; then
+      echo "SSH hardening unavailable: $username has no safe authorized_keys" >&2
+    else
+      copy_root_key=1
+    fi
+    if (( copy_root_key )); then
+      echo "Copying root's authorized_keys to $username"
+      root_keys="$(system_path /root/.ssh/authorized_keys)"
+      if ! runuser -u "$username" -- install -d -m 0700 -- "$user_ssh_dir" \
+        || ! runuser -u "$username" -- install -m 0600 -- /dev/stdin "$user_keys" \
+          <"$root_keys"; then
+        echo "SSH hardening unavailable: could not install root's key for $username" >&2
+      fi
+    fi
+  fi
+
+  if safe_authorized_keys "$username" "$user_home"; then
+    harden_status=0
+    harden_server_ssh "$username" "$user_home" || harden_status=$?
+    if (( harden_status != 0 && harden_status != 2 )); then
+      echo "SSH hardening failed; stopping before install handoff." >&2
+      exit 1
+    fi
+  else
+    echo "SSH hardening unavailable: $username has no safe authorized_keys" >&2
+  fi
+
+  if ! command -v git >/dev/null 2>&1; then
+    echo "Installing git, which the clone needs"
+    dnf install -y --repo=fedora --repo=updates --from-repo=fedora,updates git
+  fi
+
+  # Create or advance the checkout as the target user. A root-owned .git in a
+  # user's home would break every later update.
+  PANAMA_PATH="$bootstrap_home/.local/share/Panama"
+  BOOTSTRAP_USER="$username"
+  prepare_panama_checkout "$PANAMA_PATH"
+
+  echo "Handing off to install as $username"
+  verified_install_handoff 1
+fi
+
+# git is the one dependency the clone itself needs. Everything else -- gum
+# included -- is bootstrapped by `install`.
+if ! command -v git >/dev/null 2>&1; then
+  echo "Installing git, which the clone needs"
+  sudo dnf install -y --repo=fedora --repo=updates --from-repo=fedora,updates git
+fi
+
+prepare_panama_checkout "$PANAMA_PATH"
+
+# A shell invoked from automation can have a pipe as stdin, while the first
+# thing install runs is the interview, which has to be able to ask.
+# Reattach the terminal when there is one; without one the interview will say
+# so itself.
+# The probe actually opens /dev/tty rather than testing -r: a process with no
+# controlling terminal passes -r and then fails the redirect.
+handoff_tty=0
+if [[ ! -t 0 ]] && (exec </dev/tty) 2>/dev/null; then
+  handoff_tty=1
+fi
+verified_install_handoff "$handoff_tty"
@@ -24,7 +24,3 @@ else
  fi
  export PATH
 fi
-# rustup writes this file, and initial-packages installs rustup rather than
-# running rustup-init -- so on a fresh machine it does not exist yet and an
-# unguarded source made every single shell start with an error.
-[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"
@@ -3,11 +3,19 @@
 # Aliases I like
 alias :q="exit"
 alias :wq="exit"
-alias startsunshine="systemctl --user restart sunshine.service"
 alias sourcerc="source ~/.bashrc"
 alias c="clear"
 alias shutdown="systemctl poweroff"
-alias update-grub="sudo grub-mkconfig -o /etc/grub2-efi.cfg"
+# The config target differs by firmware: EFI machines regenerate the EFI
+# config, BIOS machines /boot/grub2/grub.cfg -- writing the EFI path on a BIOS
+# machine updates a file nothing boots from.
+update-grub() {
+  if [ -d /sys/firmware/efi ]; then
+    sudo grub2-mkconfig -o /etc/grub2-efi.cfg
+  else
+    sudo grub2-mkconfig -o /boot/grub2/grub.cfg
+  fi
+}
 alias nvidia-smi-docker='sudo docker run --rm --gpus all --privileged nvidia/cuda:12.8.1-base-ubuntu24.04 nvidia-smi'
 alias ncconnect='sudo docker exec -u www-data -it nextcloud-aio-nextcloud bash'
 alias avante='nvim -c "lua vim.defer_fn(function()require(\"avante.api\").zen_mode()end, 100)"'
@@ -32,7 +40,8 @@ alias ls='eza -lh --group-directories-first --icons'
 alias lsa='ls -a'
 alias lt='eza --tree --level=2 --long --icons --git'
 alias lta='lt -a'
-alias ff="fzf --preview 'batcat --style=numbers --color=always {}'"
+# Fedora's bat installs /usr/bin/bat; batcat is the Debian name.
+alias ff="fzf --preview 'bat --style=numbers --color=always {}'"

 # Directories
 alias ..='cd ..'
@@ -1,5 +1,18 @@
 #!/usr/bin/env bash

+# Personal environment -- API keys, tokens -- lives OUTSIDE the checkout,
+# where agents, backup tools and `panama update` walk, and is kept owner-only
+# every time it is read: a secrets file that drifts to 644 is quietly
+# re-tightened rather than trusted. Sourced first, because settings below
+# (PANAMA_SSH_TMUX) read it. (config/bash/env, its old home inside the repo,
+# is still sourced by .bashrc's glob if a machine has not been migrated yet.)
+PANAMA_ENV="${XDG_CONFIG_HOME:-$HOME/.config}/panama/env"
+if [ -f "$PANAMA_ENV" ]; then
+  [ "$(stat -c %a "$PANAMA_ENV" 2>/dev/null)" = "600" ] || chmod 600 "$PANAMA_ENV"
+  . "$PANAMA_ENV"
+fi
+unset PANAMA_ENV
+
 # Editor used by CLI
 export EDITOR="nvim"
 export SUDO_EDITOR="$EDITOR"
@@ -22,20 +35,33 @@ export DOTNETPATH="$HOME/.dotnet/tools"
 # Set complete path
 export PATH="$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PANAMA_PATH/bin:$BUN_INSTALL/bin:$CARGO_PATH/bin:$PNPM_HOME/bin:$PYENV_ROOT/bin:$HOME/.rbenv/bin:/usr/lib/ccache/bin/:$GOPATH/bin:$DOTNETPATH"

+# rustup writes this file, and initial-packages installs rustup rather than
+# running rustup-init -- so on a fresh machine it does not exist yet and an
+# unguarded source made every single shell start with an error.
+[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"
+
 # Nvm. Guarded because the file belongs to the nvm package: before that is
 # installed it does not exist, and an unconditional source means every shell on
 # a fresh machine opens with an error.
 [ -f /etc/profile.d/nvm.sh ] && source /etc/profile.d/nvm.sh
 # Auto-switch Node version when entering a directory with .nvmrc
 _nvm_auto_use() {
-  if [[ -f .nvmrc ]]; then
+  # Guarded on nvm actually being loaded: without this, a machine where the
+  # nvm profile script is absent printed "command not found" on every single
+  # prompt in any directory carrying a .nvmrc.
+  if [[ -f .nvmrc ]] && type -t nvm >/dev/null 2>&1; then
    nvm use --silent
  fi
 }
 export PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }_nvm_auto_use"

-# Auto-start or attach tmux for SSH interactive shells
-if [[ -n "$SSH_CONNECTION" && -z "$TMUX" && $- == *i* ]]; then
+# Auto-start or attach tmux for SSH interactive shells. A deliberate Panama
+# behavior (tmux is in initial-packages, and a dropped SSH session keeping its
+# work is the point), but guarded: it must not replace the shell of someone
+# whose machine lacks tmux, and PANAMA_SSH_TMUX=off turns it off for people
+# who want a plain shell -- set it in ~/.config/panama/env.
+if [[ -n "$SSH_CONNECTION" && -z "$TMUX" && $- == *i* &&
+  "${PANAMA_SSH_TMUX:-on}" != "off" ]] && command -v tmux >/dev/null 2>&1; then
  exec tmux new-session -A -s main
 fi

@@ -1,8 +0,0 @@
-# see `man dnf.conf` for defaults and possible options
-
-[main]
-fastestmirror=True
-max_parallel_downloads=10
-defaultyes=True
-keepcache=True
-deltarpm=True
@@ -0,0 +1,8 @@
+# A stray press of the power button should ask, not act. Fedora's logind
+# default is HandlePowerKey=poweroff -- an instant, unconfirmed shutdown.
+# Panama binds the key in the compositor to open its power menu instead
+# (keybinds.lua), the way GNOME turns the key into a dialog, so logind is
+# told to stand down. Holding the button still hard-cuts through firmware,
+# which remains the escape hatch this file cannot and should not remove.
+[Login]
+HandlePowerKey=ignore
@@ -0,0 +1,35 @@
+# Clear the mountpoint before starting, so a start that follows a crash lands
+# on clean ground.
+#
+# This service provides the fuse mount at /run/user/$UID/doc, and bwrap binds
+# doc/by-app/<id> into every flatpak sandbox it builds. No mount, no sandbox,
+# no application -- all of them, not one, because they all share this.
+#
+# The shipped unit is Type=dbus with Restart=no, so nothing restarts it on
+# failure: it comes back only when something next calls its bus name. On this
+# machine that was a flatpak launching two seconds after the daemon exited
+# 21, and the activation raced the dying instance's fuse state and came up
+# with no mount at all. systemctl then reports active (running) -- the
+# fusermount3 helper is even still there as a child -- while every new sandbox
+# fails. Nothing running at the time notices, because a sandbox needs the
+# mount only while it is being built, so the breakage surfaces whenever you
+# next open something you had not opened yet. Here that was three days later,
+# and it was the second time: the first was written off as a one-off.
+#
+# `-` because a clean start has nothing to unmount and fusermount3 exits 1
+# saying so, which is not a failure to start on.
+#
+# The unmount alone did not close the hole: the third recurrence (2026-08-26)
+# started on ground the ExecStartPre had cleaned and still came up with no
+# mount, sitting active-and-broken for fourteen hours until the next fresh
+# flatpak launch found it. Hence ExecStartPost: the unit is not "started"
+# until the mount it exists to provide actually exists. Type=dbus declares
+# readiness at bus-name acquisition, which can land before the fuse thread
+# has the mount up, so this polls rather than checks once. If five seconds
+# pass without a mount, the start fails -- loudly, in the journal, as failed
+# -- and the next bus activation retries from the ExecStartPre cleanup
+# instead of every sandbox build failing against a unit that claims to be
+# fine.
+[Service]
+ExecStartPre=-/usr/bin/fusermount3 -u /run/user/%U/doc
+ExecStartPost=/usr/bin/timeout 5 /bin/sh -c 'until /usr/bin/mountpoint -q /run/user/%U/doc; do /usr/bin/sleep 0.2; done'
@@ -0,0 +1,9 @@
+# External monitor brightness (DDC/CI) on GPUs that are not "VGA".
+#
+# ddcutil ships 60-ddcutil-i2c.rules, which grants the seated user access to
+# the GPU's i2c buses -- but only when the GPU's PCI class is 0x030000 (VGA
+# compatible controller). An AMD iGPU that is not the primary boot display
+# enumerates as 0x038000 (Display controller) instead, so every DDC bus it
+# exposes stays root-only and the Brightness service reads EACCES. Same grant,
+# broadened to the class that hardware actually reports.
+SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{class}=="0x038000", TAG+="uaccess"
@@ -1,17 +1,9 @@
 # espanso match file
 # https://espanso.org/docs/
+# Name and email triggers (:fn, :em, ...) are NOT here: they are personal, and
+# this file is shared. setup-identity seeds them into match/identity.yml --
+# per-machine, gitignored, yours to edit -- from the install interview.
 matches:
-  # Name
-  - trigger: ":fn"
-    replace: "Gabriel Brown"
-  - trigger: ":fin"
-    replace: "Gabriel A Brown"
-  # Email
-  - trigger: ":em"
-    replace: "[email protected]"
-  - trigger: ":empro"
-    replace: "[email protected]"
-
  # Date
  - trigger: ":date"
    replace: "{{mydate}}"
@@ -147,18 +139,6 @@ matches:
  - trigger: "dokcer"
    replace: "docker"

-  - trigger: "gborwn"
-    replace: "gbrown"
-
-  - trigger: "gbrwon"
-    replace: "gbrown"
-
-  - trigger: "gbronw"
-    replace: "gbrown"
-
-  - trigger: "grbown"
-    replace: "gbrown"
-
  - trigger: "restrat"
    replace: "restart"

@@ -1,8 +0,0 @@
-file:///home/gib/Documents Documents
-file:///home/gib/Documents/Code Code
-file:///home/gib/Downloads Downloads
-file:///home/gib/Music Music
-file:///home/gib/Pictures Pictures
-file:///home/gib/Videos Videos
-file:///home/gib/.local/share/Panama Panama
-smb://server-gib.local/homes/ Gib's Server
@@ -0,0 +1,6 @@
+file://$HOME/Documents Documents
+file://$HOME/Downloads Downloads
+file://$HOME/Music Music
+file://$HOME/Pictures Pictures
+file://$HOME/Videos Videos
+file://$HOME/.local/share/Panama Panama
@@ -1,36 +1,63 @@
-@define-color accent_color rgba(192,153,255,0.8);
-@define-color accent_bg_color rgba(130,170,255,0.8);
-@define-color accent_fg_color #ffffff;
-@define-color destructive_color #ff7b63;
-@define-color destructive_bg_color #c01c28;
-@define-color destructive_fg_color #ffffff;
-@define-color success_color #8ff0a4;
-@define-color success_bg_color #26a269;
-@define-color success_fg_color #ffffff;
-@define-color warning_color #f8e45c;
-@define-color warning_bg_color #cd9309;
-@define-color warning_fg_color rgba(0, 0, 0, 0.8);
-@define-color error_color #ff7b63;
-@define-color error_bg_color #c01c28;
-@define-color error_fg_color #ffffff;
-@define-color window_bg_color rgba(46,47,61,0.98);
-@define-color window_fg_color #ffffff;
-@define-color view_bg_color rgba(46,47,61,0.98);
-@define-color view_fg_color #ffffff;
-@define-color headerbar_bg_color rgba(46,47,61,0.98);
-@define-color headerbar_fg_color #ffffff;
-@define-color headerbar_border_color #ffffff;
-@define-color headerbar_backdrop_color @window_bg_color;
-@define-color headerbar_shade_color rgba(46,47,61,0.05);
-@define-color card_bg_color rgba(180, 200, 255, 0.15);
-@define-color card_fg_color #ffffff;
-@define-color card_shade_color rgba(0, 0, 0, 0.36);
-@define-color dialog_bg_color rgba(46,47,61,0.98);
-@define-color dialog_fg_color #ffffff;
-@define-color popover_bg_color rgba(46,47,61,0.98);
-@define-color popover_fg_color #ffffff;
-@define-color shade_color rgba(0, 0, 0, 0);
-@define-color scrollbar_outline_color rgba(0, 0, 0, 0.5);
+/* Panama regenerates the block below from the active theme's palette, and only
+ * the block: every rule outside the markers belongs to the vendored theme and
+ * is never touched. Edit the theme, not this file -- the next theme change
+ * overwrites whatever is between the markers. The values shipped here are Tokyo
+ * Moon, the default dark theme, so the file is valid before it has ever been
+ * rewritten. See quickshell/scripts/panama-theme-apps. */
+/* PANAMA THEME BEGIN */
+/* Generated from the "moon" theme by panama-theme-apps. Edit the
+ * theme, not this block -- the next theme change overwrites it. */
+@define-color accent_bg_color #82aaff;
+@define-color accent_color #65bcff;
+@define-color accent_fg_color #1e2030;
+@define-color destructive_bg_color #c53b53;
+@define-color destructive_color #ff757f;
+@define-color destructive_fg_color #c8d3f5;
+@define-color success_bg_color #c3e88d;
+@define-color success_color #c3e88d;
+@define-color success_fg_color #1e2030;
+@define-color warning_bg_color #ffc777;
+@define-color warning_color #ffc777;
+@define-color warning_fg_color #1e2030;
+@define-color error_bg_color #c53b53;
+@define-color error_color #ff757f;
+@define-color error_fg_color #c8d3f5;
+@define-color window_bg_color #2e2f3d;
+@define-color window_fg_color #c8d3f5;
+@define-color view_bg_color #222436;
+@define-color view_fg_color #c8d3f5;
+@define-color headerbar_bg_color #2e2f3d;
+@define-color headerbar_fg_color #c8d3f5;
+@define-color headerbar_border_color #3b4261;
+@define-color headerbar_backdrop_color #1e2030;
+@define-color headerbar_shade_color rgba(30, 32, 48, 0.08);
+@define-color headerbar_darker_shade_color rgba(30, 32, 48, 0.9);
+@define-color sidebar_bg_color #1e2030;
+@define-color sidebar_fg_color #c8d3f5;
+@define-color sidebar_backdrop_color #1e2030;
+@define-color sidebar_shade_color rgba(59, 66, 97, 0.08);
+@define-color sidebar_border_color rgba(59, 66, 97, 0.36);
+@define-color secondary_sidebar_bg_color #1e2030;
+@define-color secondary_sidebar_fg_color #c8d3f5;
+@define-color secondary_sidebar_backdrop_color #1e2030;
+@define-color secondary_sidebar_shade_color rgba(30, 32, 48, 0.25);
+@define-color secondary_sidebar_border_color rgba(59, 66, 97, 0.36);
+@define-color card_bg_color #2f334d;
+@define-color card_fg_color #c8d3f5;
+@define-color card_shade_color rgba(30, 32, 48, 0.25);
+@define-color dialog_bg_color #21212f;
+@define-color dialog_fg_color #c8d3f5;
+@define-color popover_bg_color #21212f;
+@define-color popover_fg_color #c8d3f5;
+@define-color popover_shade_color rgba(30, 32, 48, 0.25);
+@define-color thumbnail_bg_color #2f334d;
+@define-color thumbnail_fg_color #c8d3f5;
+@define-color shade_color rgba(30, 32, 48, 0.25);
+@define-color scrollbar_outline_color rgba(30, 32, 48, 0.5);
+/* PANAMA THEME END */
+
+/* The GNOME named palette below is reference, not theme: applications ask for
+ * @red_3 by name and expect GNOME's red. It stays outside the block. */
@define-color blue_1 #99c1f1;
@define-color blue_2 #62a0ea;
@define-color blue_3 #3584e4;
@@ -1,53 +1,64 @@
 /* GTK NAMED COLORS ---------------- use responsibly! */
-@define-color accent_bg_color RGB(130 170 255 / 80%);
-
-@define-color destructive_bg_color #c01c28;
-@define-color destructive_fg_color white;
-@define-color success_bg_color #26a269;
-@define-color success_fg_color white;
-@define-color warning_bg_color #cd9309;
-@define-color warning_fg_color RGB(0 0 0 / 80%);
-@define-color error_bg_color #c01c28;
-@define-color error_fg_color white;
-@define-color accent_color oklab(from @accent_bg_color max(l, 0.85) a b);
-@define-color destructive_color oklab(from @destructive_bg_color max(l, 0.85) a b);
-@define-color success_color oklab(from @success_bg_color max(l, 0.85) a b);
-@define-color warning_color oklab(from @warning_bg_color max(l, 0.85) a b);
-@define-color error_color oklab(from @error_bg_color max(l, 0.85) a b);
-
+/* Panama regenerates the block below from the active theme's palette, and only
+ * the block: every rule outside the markers belongs to the vendored theme and
+ * is never touched. Edit the theme, not this file -- the next theme change
+ * overwrites whatever is between the markers. The values shipped here are Tokyo
+ * Moon, the default dark theme, so the file is valid before it has ever been
+ * rewritten. See quickshell/scripts/panama-theme-apps. */
+/* PANAMA THEME BEGIN */
+/* Generated from the "moon" theme by panama-theme-apps. Edit the
+ * theme, not this block -- the next theme change overwrites it. */
+@define-color accent_bg_color #82aaff;
+@define-color accent_color #65bcff;
+@define-color accent_fg_color #1e2030;
+@define-color destructive_bg_color #c53b53;
+@define-color destructive_color #ff757f;
+@define-color destructive_fg_color #c8d3f5;
+@define-color success_bg_color #c3e88d;
+@define-color success_color #c3e88d;
+@define-color success_fg_color #1e2030;
+@define-color warning_bg_color #ffc777;
+@define-color warning_color #ffc777;
+@define-color warning_fg_color #1e2030;
+@define-color error_bg_color #c53b53;
+@define-color error_color #ff757f;
+@define-color error_fg_color #c8d3f5;
@define-color window_bg_color #2e2f3d;
-@define-color window_fg_color white;
-@define-color view_bg_color @window_bg_color
-@define-color view_fg_color white;
-@define-color headerbar_bg_color @window_bg_color
-@define-color headerbar_fg_color white;
-@define-color headerbar_border_color white;
-@define-color headerbar_backdrop_color @window_bg_color;
-@define-color headerbar_shade_color RGB(46 47 61 / 8%);
-@define-color headerbar_darker_shade_color RGB(0, 0, 6, 0.9);
+@define-color window_fg_color #c8d3f5;
+@define-color view_bg_color #222436;
+@define-color view_fg_color #c8d3f5;
+@define-color headerbar_bg_color #2e2f3d;
+@define-color headerbar_fg_color #c8d3f5;
+@define-color headerbar_border_color #3b4261;
+@define-color headerbar_backdrop_color #1e2030;
+@define-color headerbar_shade_color rgba(30, 32, 48, 0.08);
+@define-color headerbar_darker_shade_color rgba(30, 32, 48, 0.9);
+@define-color sidebar_bg_color #1e2030;
+@define-color sidebar_fg_color #c8d3f5;
+@define-color sidebar_backdrop_color #1e2030;
+@define-color sidebar_shade_color rgba(59, 66, 97, 0.08);
+@define-color sidebar_border_color rgba(59, 66, 97, 0.36);
+@define-color secondary_sidebar_bg_color #1e2030;
+@define-color secondary_sidebar_fg_color #c8d3f5;
+@define-color secondary_sidebar_backdrop_color #1e2030;
+@define-color secondary_sidebar_shade_color rgba(30, 32, 48, 0.25);
+@define-color secondary_sidebar_border_color rgba(59, 66, 97, 0.36);
+@define-color card_bg_color #2f334d;
+@define-color card_fg_color #c8d3f5;
+@define-color card_shade_color rgba(30, 32, 48, 0.25);
+@define-color dialog_bg_color #21212f;
+@define-color dialog_fg_color #c8d3f5;
+@define-color popover_bg_color #21212f;
+@define-color popover_fg_color #c8d3f5;
+@define-color popover_shade_color rgba(30, 32, 48, 0.25);
+@define-color thumbnail_bg_color #2f334d;
+@define-color thumbnail_fg_color #c8d3f5;
+@define-color shade_color rgba(30, 32, 48, 0.25);
+@define-color scrollbar_outline_color rgba(30, 32, 48, 0.5);
+/* PANAMA THEME END */

-@define-color sidebar_bg_color #3c3c4b;
-@define-color sidebar_fg_color white;
-@define-color sidebar_backdrop_color #3c3c4b;
-@define-color sidebar_shade_color RGB(60 60 75/8%);
-@define-color sidebar_border_color RGB(75 75 90/36%);
-@define-color secondary_sidebar_bg_color #3c3c4b;
-@define-color secondary_sidebar_fg_color white;
-@define-color secondary_sidebar_backdrop_color #3c3c4b;
-@define-color secondary_sidebar_shade_color RGB(0 0 6/25%);
-@define-color secondary_sidebar_border_color RGB(0 0 6/36%);
-@define-color card_bg_color RGB(180 200 255/15%);
-@define-color card_fg_color white;
-@define-color card_shade_color RGB(46 47 61/8%);
-@define-color dialog_bg_color @window_bg_color;
-@define-color dialog_fg_color white;
-@define-color popover_bg_color @window_bg_color;
-@define-color popover_fg_color white;
-@define-color popover_shade_color RGB(0 0 6/25%);
-@define-color thumbnail_bg_color @window_bg_color;
-@define-color thumbnail_fg_color white;
-@define-color shade_color RGB(0 0 6/25%);
-@define-color scrollbar_outline_color RGB(0 0 12/95%);
+/* The GNOME named palette below is reference, not theme: applications ask for
+ * @red_3 by name and expect GNOME's red. It stays outside the block. */
@define-color blue_1 #99c1f1;
@define-color blue_2 #62a0ea;
@define-color blue_3 #3584e4;
@@ -1,53 +1,64 @@
 /* GTK NAMED COLORS ---------------- use responsibly! */
-@define-color accent_bg_color RGB(130 170 255 / 80%);
-
-@define-color destructive_bg_color #c01c28;
-@define-color destructive_fg_color white;
-@define-color success_bg_color #26a269;
-@define-color success_fg_color white;
-@define-color warning_bg_color #cd9309;
-@define-color warning_fg_color RGB(0 0 0 / 80%);
-@define-color error_bg_color #c01c28;
-@define-color error_fg_color white;
-@define-color accent_color oklab(from @accent_bg_color max(l, 0.85) a b);
-@define-color destructive_color oklab(from @destructive_bg_color max(l, 0.85) a b);
-@define-color success_color oklab(from @success_bg_color max(l, 0.85) a b);
-@define-color warning_color oklab(from @warning_bg_color max(l, 0.85) a b);
-@define-color error_color oklab(from @error_bg_color max(l, 0.85) a b);
-
+/* Panama regenerates the block below from the active theme's palette, and only
+ * the block: every rule outside the markers belongs to the vendored theme and
+ * is never touched. Edit the theme, not this file -- the next theme change
+ * overwrites whatever is between the markers. The values shipped here are Tokyo
+ * Moon, the default dark theme, so the file is valid before it has ever been
+ * rewritten. See quickshell/scripts/panama-theme-apps. */
+/* PANAMA THEME BEGIN */
+/* Generated from the "moon" theme by panama-theme-apps. Edit the
+ * theme, not this block -- the next theme change overwrites it. */
+@define-color accent_bg_color #82aaff;
+@define-color accent_color #65bcff;
+@define-color accent_fg_color #1e2030;
+@define-color destructive_bg_color #c53b53;
+@define-color destructive_color #ff757f;
+@define-color destructive_fg_color #c8d3f5;
+@define-color success_bg_color #c3e88d;
+@define-color success_color #c3e88d;
+@define-color success_fg_color #1e2030;
+@define-color warning_bg_color #ffc777;
+@define-color warning_color #ffc777;
+@define-color warning_fg_color #1e2030;
+@define-color error_bg_color #c53b53;
+@define-color error_color #ff757f;
+@define-color error_fg_color #c8d3f5;
@define-color window_bg_color #2e2f3d;
-@define-color window_fg_color white;
-@define-color view_bg_color @window_bg_color
-@define-color view_fg_color white;
-@define-color headerbar_bg_color @window_bg_color
-@define-color headerbar_fg_color white;
-@define-color headerbar_border_color white;
-@define-color headerbar_backdrop_color @window_bg_color;
-@define-color headerbar_shade_color RGB(46 47 61 / 8%);
-@define-color headerbar_darker_shade_color RGB(0, 0, 6, 0.9);
+@define-color window_fg_color #c8d3f5;
+@define-color view_bg_color #222436;
+@define-color view_fg_color #c8d3f5;
+@define-color headerbar_bg_color #2e2f3d;
+@define-color headerbar_fg_color #c8d3f5;
+@define-color headerbar_border_color #3b4261;
+@define-color headerbar_backdrop_color #1e2030;
+@define-color headerbar_shade_color rgba(30, 32, 48, 0.08);
+@define-color headerbar_darker_shade_color rgba(30, 32, 48, 0.9);
+@define-color sidebar_bg_color #1e2030;
+@define-color sidebar_fg_color #c8d3f5;
+@define-color sidebar_backdrop_color #1e2030;
+@define-color sidebar_shade_color rgba(59, 66, 97, 0.08);
+@define-color sidebar_border_color rgba(59, 66, 97, 0.36);
+@define-color secondary_sidebar_bg_color #1e2030;
+@define-color secondary_sidebar_fg_color #c8d3f5;
+@define-color secondary_sidebar_backdrop_color #1e2030;
+@define-color secondary_sidebar_shade_color rgba(30, 32, 48, 0.25);
+@define-color secondary_sidebar_border_color rgba(59, 66, 97, 0.36);
+@define-color card_bg_color #2f334d;
+@define-color card_fg_color #c8d3f5;
+@define-color card_shade_color rgba(30, 32, 48, 0.25);
+@define-color dialog_bg_color #21212f;
+@define-color dialog_fg_color #c8d3f5;
+@define-color popover_bg_color #21212f;
+@define-color popover_fg_color #c8d3f5;
+@define-color popover_shade_color rgba(30, 32, 48, 0.25);
+@define-color thumbnail_bg_color #2f334d;
+@define-color thumbnail_fg_color #c8d3f5;
+@define-color shade_color rgba(30, 32, 48, 0.25);
+@define-color scrollbar_outline_color rgba(30, 32, 48, 0.5);
+/* PANAMA THEME END */

-@define-color sidebar_bg_color #3c3c4b;
-@define-color sidebar_fg_color white;
-@define-color sidebar_backdrop_color #3c3c4b;
-@define-color sidebar_shade_color RGB(60 60 75/8%);
-@define-color sidebar_border_color RGB(75 75 90/36%);
-@define-color secondary_sidebar_bg_color #3c3c4b;
-@define-color secondary_sidebar_fg_color white;
-@define-color secondary_sidebar_backdrop_color #3c3c4b;
-@define-color secondary_sidebar_shade_color RGB(0 0 6/25%);
-@define-color secondary_sidebar_border_color RGB(0 0 6/36%);
-@define-color card_bg_color RGB(180 200 255/15%);
-@define-color card_fg_color white;
-@define-color card_shade_color RGB(46 47 61/8%);
-@define-color dialog_bg_color @window_bg_color;
-@define-color dialog_fg_color white;
-@define-color popover_bg_color @window_bg_color;
-@define-color popover_fg_color white;
-@define-color popover_shade_color RGB(0 0 6/25%);
-@define-color thumbnail_bg_color @window_bg_color;
-@define-color thumbnail_fg_color white;
-@define-color shade_color RGB(0 0 6/25%);
-@define-color scrollbar_outline_color RGB(0 0 12/95%);
+/* The GNOME named palette below is reference, not theme: applications ask for
+ * @red_3 by name and expect GNOME's red. It stays outside the block. */
@define-color blue_1 #99c1f1;
@define-color blue_2 #62a0ea;
@define-color blue_3 #3584e4;
@@ -25,7 +25,7 @@ Last live audit: 2026-08-17, Fedora 44, Hyprland 0.56.2, Quickshell 0.3.0.
 | Calendar agenda | Existing GNOME, Google, iCloud, and Nextcloud sources through Evolution Data Server | Live |
 | Control Center | Wi-Fi, Bluetooth, audio input/output, Caffeine, Night Light, Focus, Home Assistant favorites, and KDE Connect phone continuity | Live |
 | Focus sessions | Persistent workspace-bound timer, DND/caffeine coordination, Signal Glass controls | Live |
-| Brightness | Appears only when a backlight device exists | Live, not applicable on this monitor |
+| Brightness | Appears only when a backlight device exists | Live where the hardware exposes it |
 | AppIndicator / tray | Native StatusNotifierItem host and themed menus | Live |
 | Screenshot and recording | Quickshell picker, grim/slurp/satty/wf-recorder | Live |
 | Screen text and code recognition | Local Tesseract/ZBar Read mode, selectable Prism result sheet | Live after package install |
@@ -39,6 +39,29 @@ Last live audit: 2026-08-17, Fedora 44, Hyprland 0.56.2, Quickshell 0.3.0.
 | System settings | The Settings app for display policy, appearance, desktop, sound, focus, shortcuts, and services; labeled GNOME hardware/account handoffs | Live |
 | System health and recovery | Settings → System Health, `Check System Health` in Vicinae, a degraded-only bar indicator, redacted reports, and bounded Panama-owned repairs | Live |

+## Portable machines
+
+Panama was a desktop configuration until 2026-08-22, in the code as well as on
+the machine: there was no reference to a battery, a lid, or a power source
+anywhere in it, and `hypridle.conf` said "This is a desktop" in its own header.
+
+| Capability | Panama implementation | Status |
+|---|---|---|
+| Battery level | `services/Battery.qml` reads sysfs the way Vitals reads procfs; bar indicator hides entirely without a battery | Live |
+| Power source | `panama-hw ac`; a machine with no mains supply reports as on wall power, so a desktop is never treated as running out | Live |
+| Charge threshold | Power page control, only where the firmware exposes a ceiling; written through `panama-sudo` | Live |
+| Idle timings per power source | hypridle holds one set at a time, so `panama-idle` rebuilds its config when the charger comes or goes | Live |
+| Lock on lid close | hypridle's `before_sleep_cmd` already locks, so a lid-close suspend is a locked suspend | Live |
+| Clamshell / docked | A logind `handle-lid-switch` inhibitor held while an external display is connected. No lid watcher, and a failure returns logind's default | Live, untested on a lid |
+| Display arrangement on reconnect | `Displays.plannedRestore()` reapplies a confirmed layout, refusing when the stored mode is not offered | Live |
+| Charger and low-battery notices | `StatusEvents`; the charger is ambient so DND quiets it, critical battery is not | Live |
+| Hardware predicates | `panama-hw`: laptop, battery, ac, lid-closed, external-monitor, clamshell, touchpad, nvidia | Live |
+
+The clamshell path is the one row that has not run on hardware with a lid.
+Everything testable about it is tested; the end-to-end behaviour of closing a
+real lid on a docked machine is not, and the helper's header says so rather
+than letting silence imply otherwise.
+
 ## System health and recovery

 Panama stays silent while the desktop is healthy. A compact bar indicator
@@ -91,6 +114,22 @@ a polished general-purpose desktop can go beyond the current shell.

 1. A real external RustDesk test while hyprlock is active. Local process state
   cannot prove what a remote client sees or whether input is accepted.
+2. Closing a real lid on a docked laptop. The inhibitor, the predicates and the
+   decision are all tested; the physical gesture is not.
+3. A keyboard-layout change notice. Hyprland reports the active keymap but not
+   a change event Quickshell already consumes, so this needs either polling or
+   new event plumbing, and a single-layout machine cannot test it.
+4. Sticky keys, slow keys and bounce keys. Wayland has no protocol for these,
+   so each compositor implements them for itself — mutter does, which is how
+   GNOME has them on Wayland, and Hyprland does not. There is no XKB option to
+   lean on either: the accessx option group is X11-only and does not appear in
+   evdev.lst at all (checked, not assumed — `grep -c accessx
+   /usr/share/X11/xkb/rules/evdev.lst` is 0), and Hyprland will happily store
+   `accessx:enable` as a keyboard option that nothing ever acts on. This is a
+   Hyprland gap rather than a Wayland impossibility, and the Accessibility page
+   says so in those terms; an earlier version of this line blamed X11 and sent
+   anyone who needs sticky keys to the wrong conclusion about the platform.
+5. An on-screen keyboard, for a touch or convertible machine.

 KDE Connect, the printer UI, Tesseract, and ZBar are installed and remain
 tracked in `setup/packages/hyprland-packages`.
@@ -29,13 +29,15 @@ Don't "fix" them.
 | `hyprland.lua` | Entry point. Each `require()` is its own error scope |
 | `prefs.lua` | Reads the settings file the Settings app writes. See below |
 | `env.lua` | Environment. Note the uwsm caveat below |
-| `monitors.lua` | DP-2 geometry, scaling, and the HDR decision |
+| `monitors.lua` | Monitor geometry and scaling (the Kuycon by description), and the HDR decision |
 | `looks.lua` | Colors, blur, glow, shadows, animations, VRR, scanout |
 | `input.lua` | Keyboard/mouse. Click-to-focus, like GNOME |
 | `rules.lua` | Window rules, gaming rules, layer rules for the shell |
-| `keybinds.lua` | The full keymap |
+| `keybinds.lua` | The full keymap, including the custom shortcuts the Settings app stores |
+| `actions.lua` | Named-action resolver: the whitelist tables that turn stored `{kind, target}` data into binds, gestures — never into free-form commands |
 | `autostart.lua` | Session startup |
 | `overrides.lua` | Per-machine escape hatch, loaded last |
+| `shaders/` | Whole-screen color-filter shaders (grayscale and the three color-blindness corrections) `looks.lua` maps the `colorFilter` setting onto |
 | `hyprlock.conf` / `hypridle.conf` / `hyprpaper.conf` / `hyprtoolkit.conf` | Ecosystem tools (hyprlang) |

 Validate any change without leaving your session:
@@ -119,7 +121,7 @@ shipped one, so a hand-edited `settings.json` cannot cost you a keymap.
 Every `hl.bind` must pass a `description`. Hyprland reports Lua-defined binds
 with dispatcher `__lua` and a bytecode offset as the argument, so a bind without
 one has nothing readable beside its chord, and the Settings app drops it from the
-Input & Shortcuts page rather than showing a mystery row.
+Keyboard page under Input rather than showing a mystery row.
 `tests/quickshell/keybinds-contract` fails if any bind lacks a description, so
 this cannot regress silently.

@@ -283,7 +285,9 @@ The mental model is unchanged from Forge:
 | `SHIFT` / `ALT + Print` | Screenshot screen / window immediately |
 | `SUPER + SHIFT + S` | Screen Intelligence — read text and codes from a selection |
 | `SUPER + SHIFT + P` | Color picker |
-| `CTRL + ALT + L` | Lock (SUPER+L is "focus right") |
+| `CTRL + ALT + L` · `SUPER + Backspace` | Lock (SUPER+L is "focus right") |
+| `SUPER + /` | Every shortcut, on screen. Reads the live keymap, so a rebind shows here |
+| `SUPER + ALT + T/N/W/F/C/E` | Go to that application if it is open, rather than starting another |
 | `CTRL + ALT + Delete` | Power menu |

 ### Apps
@@ -364,7 +368,7 @@ These are the places a 1:1 port was impossible, and what was done instead:
  behaviors, keeping the horizontal/vertical and grow/shrink pairing.
 - **Overview on `SUPER + grave`, not a bare SUPER tap.** Tap-detection on a
  modifier misfires when you're quick with SUPER combos.
- **Lock on `CTRL + ALT + L`.** `SUPER + L` is "focus right" in this keymap.
+- **Lock on `CTRL + ALT + L` or `SUPER + Backspace`.** `SUPER + L` is "focus right" in this keymap.
 - **`SUPER + grave` was Forge's "cycle windows of same app"**, which Hyprland
  has no equivalent for. "Last window" moved to `SUPER + SHIFT + grave`.
 - **`gnome-control-center` is launched with `XDG_CURRENT_DESKTOP=GNOME`**,
@@ -0,0 +1,226 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Named actions
+--
+-- The one thing that makes it safe for settings.json to describe a shortcut.
+--
+-- Panama Settings lets a person invent a keyboard shortcut and assign a
+-- four-finger gesture. Both are stored in the same user-editable JSON file the
+-- rest of the desktop reads, and both have to end up as something the
+-- compositor executes -- which is exactly the shape of every configuration
+-- format that turned out to be a shell injection.
+--
+-- It is not one here, and this file is why. A stored action is DATA:
+--
+--   { kind = "app" | "shell" | "window", target = "<id>", label = "<text>" }
+--
+-- `kind` is an enum with three members. `target` is either a key of one of the
+-- whitelist tables below -- whose values are literals written here, in Lua, by
+-- a human -- or, for `app`, an identifier that has to match a character class
+-- containing no shell metacharacter at all, and which is then quoted as a
+-- single argv element for panama-launch rather than pasted into a command.
+--
+-- So the worst a hand-edited (or maliciously written) settings file can do is
+-- pick a different entry from a list that is fixed at ship time, or launch an
+-- application by id. It cannot introduce a command. There is no path from a
+-- stored string to a new exec string; the table lookups are the only source of
+-- one.
+--
+-- Everything invalid returns nil and the caller skips the bind or gesture --
+-- the prefs.lua philosophy: never raise, never guess. A malformed entry costs
+-- one shortcut, never the keymap and never the compositor.
+--
+-- Required by keybinds.lua (custom shortcuts) and input.lua (four-finger
+-- gestures). services/Keybinds.qml's describeAction() is the QML mirror of the
+-- vocabulary below; the two lists have to be edited together.
+-- ─────────────────────────────────────────────────────────────────────────────
+
+local actions = {}
+
+-- ── Shell verbs ─────────────────────────────────────────────────────────────
+--
+-- Every entry is a command string written HERE. Nothing stored anywhere else
+-- contributes a character to one; `target` only chooses which of these to use.
+--
+-- The `qs ipc call` targets and functions are the ones quickshell/shell.qml
+-- actually registers -- an IpcHandler silently declines to register a function
+-- it cannot type-check, so a verb invented here would be a shortcut that does
+-- nothing. Checked against shell.qml, not remembered.
+--
+-- The three that are not IPC (`launcher`, `color-picker`, `lock`) are the same
+-- literal commands the shipped binds in keybinds.lua use, for the same reason
+-- they use them: they are the tools, not the shell.
+local SHELL = {
+    ["dnd-toggle"]         = { label = "Do Not Disturb",       command = "qs ipc call notifications dnd" },
+    ["notifications"]      = { label = "Notifications",        command = "qs ipc call notifications toggle" },
+    ["overview"]           = { label = "Overview",             command = "qs ipc call overview toggle" },
+    ["launcher"]           = { label = "Launcher",             command = "vicinae toggle" },
+    ["clipboard"]          = { label = "Clipboard history",    command = "qs ipc call clipboard toggle" },
+    ["screenshot"]         = { label = "Screenshot / record",  command = "qs ipc call capture open" },
+    ["screenshot-screen"]  = { label = "Screenshot: whole screen", command = "qs ipc call capture screenNow" },
+    ["screenshot-window"]  = { label = "Screenshot: window",   command = "qs ipc call capture windowNow" },
+    ["screen-intelligence"]= { label = "Screen Intelligence",  command = "qs ipc call screen-intelligence open" },
+    ["color-picker"]       = { label = "Color picker",         command = "hyprpicker -a -f hex" },
+    ["quick-settings"]     = { label = "Quick settings",       command = "qs ipc call quicksettings toggle" },
+    ["settings"]           = { label = "Settings",             command = "qs ipc call settings toggle" },
+    ["cheatsheet"]         = { label = "Keyboard shortcuts",   command = "qs ipc call cheatsheet toggle" },
+    ["focus-session"]      = { label = "Focus session",        command = "qs ipc call focus reveal" },
+    ["caffeine"]           = { label = "Keep awake",           command = "qs ipc call caffeine toggle" },
+    ["night-light"]        = { label = "Night Light",          command = "qs ipc call night-light toggle" },
+    ["activity"]           = { label = "Activity",             command = "qs ipc call activity toggle" },
+    ["power-menu"]         = { label = "Power menu",           command = "qs ipc call powermenu toggle" },
+    ["lock"]               = { label = "Lock",                 command = "loginctl lock-session" },
+}
+
+-- ── Window verbs ────────────────────────────────────────────────────────────
+--
+-- Builders rather than dispatchers, so nothing is constructed for a verb that
+-- is never chosen, and so a gesture builds its dispatcher when the fingers
+-- move rather than holding one from config time.
+--
+-- `workspace:N` is not in the table: it is ten entries that differ by a number,
+-- and the number is validated as 1..10 in `window_action` below.
+local WINDOW = {
+    ["float-toggle"] = { label = "Toggle float", build = function() return hl.dsp.window.float({ action = "toggle" }) end },
+    ["fullscreen"]   = { label = "Fullscreen",   build = function() return hl.dsp.window.fullscreen({ mode = "fullscreen" }) end },
+    ["pin"]          = { label = "Pin window",   build = function() return hl.dsp.window.pin({ action = "toggle" }) end },
+}
+
+-- Published so a contract can read the vocabulary without parsing this file,
+-- and so the ten workspace verbs have one definition rather than two.
+actions.shell_verbs = SHELL
+actions.window_verbs = WINDOW
+actions.workspace_min = 1
+actions.workspace_max = 10
+
+-- ── Targets ─────────────────────────────────────────────────────────────────
+
+-- Letters, digits, and the four punctuation marks a desktop id actually uses.
+-- Deliberately excludes every shell metacharacter, quote, slash and space, so
+-- an id that passes cannot change the meaning of a command line even before it
+-- is quoted -- the quoting below is the second lock on the same door.
+local APP_TARGET = "^[A-Za-z0-9@._%-]+$"
+
+local function valid_app_target(target)
+    return type(target) == "string"
+        and #target >= 1 and #target <= 128
+        and target:match(APP_TARGET) ~= nil
+end
+
+-- Single-quoted for the shell, with the one escape single quotes need. Same
+-- function keybinds.lua uses for the go-to patterns, and used here for the
+-- same reason: the value reaches the command as one argument.
+local function shell_quote(value)
+    return "'" .. value:gsub("'", "'\\''") .. "'"
+end
+
+-- Google RE2 metacharacters, escaped so the id matches itself literally.
+-- panama-launch takes a regular expression, and an unescaped "org.gnome.Files"
+-- would also match "orgxgnomexFiles".
+local function escape_regex(value)
+    return (value:gsub("[%^%$%(%)%%%.%[%]%*%+%-%?%{%}%|\\]", "\\%0"))
+end
+
+-- ── Resolution ──────────────────────────────────────────────────────────────
+
+local launcher_bin = "$HOME/.local/share/Panama/bin/panama-launch"
+
+-- The launch-or-focus path the shipped application keys use: raise the window
+-- if it is already open, start it if it is not. The id is the class pattern
+-- (anchored, escaped) and the thing to start; on Wayland an application's
+-- desktop id and its window class are the same string often enough that this
+-- is the right first guess, and the wrong guess costs a second window rather
+-- than an error.
+--
+-- gtk-launch activates a desktop entry by id, which is what the applications
+-- catalog in Settings offers -- a desktop id is not a binary and cannot be
+-- exec'd directly.
+local function app_action(target)
+    if not valid_app_target(target) then
+        return nil
+    end
+    local launch_command = table.concat({
+        launcher_bin,
+        "--class", shell_quote("^" .. escape_regex(target) .. "$"),
+        "--", "gtk-launch", shell_quote(target),
+    }, " ")
+    return function() return hl.dsp.exec_cmd(launch_command) end
+end
+
+local function shell_action(target)
+    if type(target) ~= "string" then
+        return nil
+    end
+    local verb = SHELL[target]
+    if verb == nil then
+        return nil
+    end
+    return function() return hl.dsp.exec_cmd(verb.command) end
+end
+
+local function window_action(target)
+    if type(target) ~= "string" then
+        return nil
+    end
+
+    local verb = WINDOW[target]
+    if verb ~= nil then
+        return verb.build
+    end
+
+    local index = target:match("^workspace:(%d+)$")
+    if index == nil then
+        return nil
+    end
+    local number = tonumber(index)
+    if number == nil or number < actions.workspace_min or number > actions.workspace_max then
+        return nil
+    end
+    return function() return hl.dsp.focus({ workspace = number }) end
+end
+
+local KINDS = {
+    app    = app_action,
+    shell  = shell_action,
+    window = window_action,
+}
+
+-- The builder for one stored entry, or nil when the entry is anything this
+-- file does not recognise. Everything above funnels through here, so there is
+-- exactly one place where a stored value becomes an action.
+local function builder(entry)
+    if type(entry) ~= "table" then
+        return nil
+    end
+    local resolve = KINDS[entry.kind]
+    if resolve == nil then
+        return nil
+    end
+    return resolve(entry.target)
+end
+
+-- For hl.bind: the dispatcher itself, or nil.
+function actions.dispatcher(entry)
+    local build = builder(entry)
+    if build == nil then
+        return nil
+    end
+    return build()
+end
+
+-- For hl.gesture: a function, which is what a gesture action has to be when it
+-- is not one of Hyprland's own built-in names ("workspace" and friends).
+function actions.gesture(entry)
+    local build = builder(entry)
+    if build == nil then
+        return nil
+    end
+    return function() hl.dispatch(build()) end
+end
+
+-- True when an entry resolves to something. Cheap enough to call twice; used
+-- where the caller wants to check before it commits to emitting anything.
+function actions.valid(entry)
+    return builder(entry) ~= nil
+end
+
+return actions
@@ -39,9 +39,30 @@ hl.on("hyprland.start", function()
    -- prompt if Panama's ever fails to come up.
    hl.exec_cmd("systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP && systemctl --user start panama-polkit-agent.service hyprpaper.service vicinae.service hypridle.service")

+    -- Pending repairs for this machine, if any. Oneshot: it checks, tells the
+    -- user when there is something to tell, and exits. Started here rather
+    -- than enabled so it belongs to the Hyprland session; see the unit.
+    hl.exec_cmd("systemctl --user start panama-migrate-notify.service")
+
+    -- Notices when a program dumps core and says so once per session. Under
+    -- GNOME, ABRT does this; here nothing did, and applications died silently.
+    hl.exec_cmd("systemctl --user start panama-crash-watch.service")
+
+    -- Text expansion. change-settings runs `espanso service register`, which
+    -- writes and enables espanso's own user unit; the explicit start makes the
+    -- first Hyprland login after a fresh install work rather than the second.
+    -- Started on its own line: unlike the units above it carries no
+    -- ConditionEnvironment, and a missing unit (espanso not yet registered)
+    -- must not muddy the start of the four that lock and wallpaper depend on.
+    hl.exec_cmd("systemctl --user start espanso.service")
+
    -- The shell: bar, dock, overview, quick settings, notifications, capture.
-    -- No systemd unit ships with quickshell, so it runs as a compositor child.
-    hl.exec_cmd("quickshell --daemonize")
+    -- A supervised unit rather than a compositor child, for the one property
+    -- a child cannot have: if the shell crashes, systemd restarts it in two
+    -- seconds instead of leaving a desktop with no bar until someone knows
+    -- what to type. The unit ships in config/local/share/systemd/user and is
+    -- started per-session here like every other Panama unit.
+    hl.exec_cmd("systemctl --user start panama-quickshell.service")

    -- Removable-media automounting. GNOME did this invisibly via gvfs+udisks;
    -- outside GNOME something has to ask udisks to mount. No tray icon: the
@@ -70,8 +91,28 @@ hl.on("hyprland.start", function()
    -- session on its own. Starting it here as well would give you two trays.
 end)

+-- Tear down what the start handler brought up.
+--
+-- This stopped `hyprland-session.target`, which does not exist on Fedora --
+-- systemctl reports "Unit not found" and the handler achieves nothing. The
+-- units started above are not children of the compositor, so nothing else
+-- stopped them either: hyprpaper, hypridle, vicinae and the polkit agent kept
+-- running after logout, and each one Requires=graphical-session.target, so
+-- that target stayed active with no session behind it.
+--
+-- The next login then failed. Both uwsm and gnome-session refuse to start into
+-- a session that is already running ("A compositor or graphical-session*
+-- target is already active!"), so "Hyprland (uwsm-managed)" and GNOME both
+-- bounced straight back to the login screen while plain Hyprland -- which
+-- makes no such check -- kept working. The desktop appeared to be the only one
+-- that functioned, when it was the one leaving the mess.
+--
+-- Stopping graphical-session.target is enough on its own: every unit above is
+-- PartOf= it, so they come down with it, and it carries StopWhenUnneeded=yes.
+-- It is stopped rather than the units listed individually so that a unit added
+-- to the start handler later cannot be forgotten here.
 hl.on("hyprland.shutdown", function()
-    hl.exec_cmd("systemctl --user stop hyprland-session.target")
+    hl.exec_cmd("systemctl --user stop graphical-session.target")
 end)

 return true
@@ -17,20 +17,16 @@
 # frame time for nothing.
 # ─────────────────────────────────────────────────────────────────────────────

+# One block for every output: per-monitor wallpaper is applied at runtime by
+# the shell (services/Wallpaper.qml) over IPC, so a per-connector block here
+# would just be one machine's connector name in everyone's config.
 wallpaper {
-    monitor = DP-2
+    monitor =
    path = ~/Pictures/Wallpapers/faroe_islands.jpg
    # cover = fill the output, cropping overflow. Matches the "zoom" picture
    # option this setup used under GNOME.
    fit_mode = cover
 }

-# Fallback for any output without its own block above.
-wallpaper {
-    monitor =
-    path = ~/Pictures/Wallpapers/faroe_islands.jpg
-    fit_mode = cover
-}
-
 ipc = on
 splash = false
@@ -6,6 +6,7 @@
 -- ─────────────────────────────────────────────────────────────────────────────

 local prefs = require("prefs")
+local actions = require("actions")

 hl.config({
    input = {
@@ -35,12 +36,85 @@ hl.config({
        -- Still focus-follows-pointer, just less twitchy.
        mouse_refocus = false,

-        -- Flat pointer response, no acceleration. Matters for gaming.
+        -- 0 = NEXT, the compositor's own default: focus goes to the next window
+        -- in the layout order. `hyprctl descriptions` publishes
+        -- map: [{"mru":2},{"cursor":1},{"next":0}], and Settings offers all
+        -- three; 0 is repeated here so nothing changes on a machine with no
+        -- settings file.
+        focus_on_close = prefs.getInt("focusOnClose", 0),
+
+        -- Flat pointer response by default, no acceleration. Matters for
+        -- gaming; Settings offers adaptive for people who want it back.
        sensitivity   = prefs.get("pointerSensitivity", 0),
-        accel_profile = "flat",
+        accel_profile = prefs.get("accelProfile", "flat"),
+
+        natural_scroll = prefs.get("naturalScroll", false),
+        scroll_factor  = prefs.get("scrollFactor", 1.0),
+        left_handed    = prefs.get("leftHanded", false),
+
+        -- Empty is a value, not an omission: it is what `hyprctl getoption`
+        -- reports as "[[EMPTY]]" before anything writes the option, and it means
+        -- "let libinput pick per device" -- two fingers on a touchpad, the wheel
+        -- on a mouse. Writing it back explicitly is the same branch a stock
+        -- Hyprland takes, and it keeps the setting reversible: without an empty
+        -- choice in the schema there would be no way back from a scroll method
+        -- once one was picked. Settings offers 2fg / edge / on_button_down /
+        -- no_scroll alongside it, the four words the option's own description
+        -- names (it publishes no map).
+        scroll_method = prefs.get("scrollMethod", ""),
+
+        -- Only consulted while scroll_method is on_button_down. 0 means the
+        -- device's own middle button.
+        scroll_button = prefs.get("scrollButton", 0),

        -- Clicking a floating window raises and focuses it.
        float_switch_override_focus = 2,
+
+        -- Every touchpad preference Settings offers is read here as well as
+        -- applied live: the live half (hyprctl eval) reaches a running
+        -- compositor, and THIS half is what survives `hyprctl reload` and the
+        -- gap before the shell starts. A schema `hypr:` entry without a
+        -- prefs.get() here is a control that quietly reverts -- the whole
+        -- Mouse & Touchpad page once had exactly that bug. Defaults must
+        -- match PreferenceSchema's; the hypr-prefs-contract checks both.
+        touchpad = {
+            tap_to_click            = prefs.get("touchpadTapToClick", true),
+            natural_scroll          = prefs.get("touchpadNaturalScroll", true),
+            disable_while_typing    = prefs.get("touchpadDisableWhileTyping", true),
+            scroll_factor           = prefs.get("touchpadScrollFactor", 1.0),
+            drag_lock               = prefs.getInt("touchpadDragLock", 0),
+            middle_button_emulation = prefs.get("touchpadMiddleButtonEmulation", false),
+            clickfinger_behavior    = prefs.get("touchpadClickfinger", false),
+
+            -- Underscores here, hyphens in the option name getoption answers to
+            -- (input:touchpad:tap-and-drag) -- the same split tap_to_click has
+            -- at the top of this table. Hyprland's own default is true; it is
+            -- repeated rather than omitted so the schema, the Lua, and the
+            -- compositor all state the same value.
+            tap_and_drag            = prefs.get("touchpadTapAndDrag", true),
+        },
+    },
+
+    -- Pointer BEHAVIOUR, as opposed to pointer appearance: how the cursor reacts
+    -- to typing and to workspace switches. The cursor's looks -- theme, size,
+    -- hardware cursors, the inactivity fade -- are a separate cursor table in
+    -- looks.lua. hl.config calls are additive per option, so the two tables
+    -- coexist; they are split by what a person would go looking for, and these
+    -- two appear on Settings' Mouse & Touchpad page rather than in Appearance.
+    cursor = {
+        hide_on_key_press = prefs.get("cursorHideWhileTyping", false),
+
+        -- An integer with three states, written from a switch: disable = 0,
+        -- enable = 1, force = 2. Settings offers the first two, so getInt is
+        -- what bridges a stored boolean to the number Hyprland wants -- the same
+        -- pairing render.cm_auto_hdr uses in looks.lua.
+        warp_on_change_workspace = prefs.getInt("cursorWarpOnWorkspaceChange", 0),
+    },
+
+    -- Tuning for the three-finger gestures registered below.
+    gestures = {
+        workspace_swipe_distance = prefs.getInt("swipeDistance", 300),
+        workspace_swipe_invert   = prefs.get("swipeInvert", true),
    },
 })

@@ -68,4 +142,34 @@ hl.gesture({ fingers = 3, direction = "horizontal", action = "workspace" })
 hl.gesture({ fingers = 3, direction = "up",         action = overview("open") })
 hl.gesture({ fingers = 3, direction = "down",       action = overview("close") })

+-- ── Four-finger gestures ────────────────────────────────────────────────────
+--
+-- The three above are the desktop's, fixed. These four are the user's: each
+-- holds a named action from settings.json, or {} for unassigned, and the
+-- vocabulary is exactly the one custom shortcuts use -- actions.lua resolves
+-- both, through the same whitelist tables, so a gesture can no more introduce
+-- a command than a keybind can.
+--
+-- Nothing is emitted for an unassigned direction. That matters more here than
+-- it looks: a registration is read at config time and there is no way to
+-- remove one afterwards, so emitting a no-op gesture for every direction would
+-- consume the four-finger swipes permanently, including for whatever the
+-- compositor might do with them later.
+--
+-- Four rather than three because three is spoken for, and because four fingers
+-- is the largest number of them a touchpad this size can tell apart.
+local custom_gestures = {
+    { pref = "gestureFourUp",    direction = "up" },
+    { pref = "gestureFourDown",  direction = "down" },
+    { pref = "gestureFourLeft",  direction = "left" },
+    { pref = "gestureFourRight", direction = "right" },
+}
+
+for _, gesture in ipairs(custom_gestures) do
+    local action = actions.gesture(prefs.get(gesture.pref, {}))
+    if action ~= nil then
+        hl.gesture({ fingers = 4, direction = gesture.direction, action = action })
+    end
+end
+
 return true
@@ -12,6 +12,7 @@
 -- ─────────────────────────────────────────────────────────────────────────────

 local prefs = require("prefs")
+local actions = require("actions")

 local mod = "SUPER"

@@ -34,6 +35,10 @@ local osd = function(action)
    return "$HOME/.config/quickshell/scripts/panama-osd " .. action
 end

+local lid = function(action)
+    return "$HOME/.config/quickshell/scripts/panama-lid " .. action
+end
+
 local dictate = function(action)
    return "$HOME/.config/quickshell/scripts/panama-dictate " .. action
 end
@@ -70,24 +75,137 @@ local function valid_chord(chord)
    return chord:match("^[%w_+%s:]+$") ~= nil
 end

+-- ── Categories ──────────────────────────────────────────────────────────────
+-- What a bind is FOR, as opposed to what it does.
+--
+-- The cheatsheet groups by this, and the Shortcuts settings page uses it too.
+-- It is recorded here rather than guessed from the description, which is what
+-- Keybinds.qml used to do: matching substrings put "Close window" and "Close
+-- the notification list" in the same group and left anything phrased unusually
+-- in whichever bucket matched first.
+--
+-- The sections of this file already ARE the categories, so a section sets one
+-- and every bind below it inherits it. That keeps the annotation to one line
+-- per section instead of one per bind, and makes the grouping impossible to
+-- forget: a new bind lands in the category of the section it was written in.
+local categories = {}
+local current_category = "Other"
+
+local function category(name)
+    current_category = name
+end
+
 local function bind(chord, action, opts)
    local override = overrides[chord]
    if valid_chord(override) then
        chord = override
    end
+    -- Keyed by the chord actually bound, so the shell can join on what
+    -- hyprctl reports without having to know about overrides.
+    categories[chord] = current_category
    return hl.bind(chord, action, opts)
 end

+-- Written where the shell can read it. Hyprland reports a Lua bind's
+-- dispatcher as `__lua` with a bytecode offset, so there is no way to attach
+-- anything to a bind that survives into `hyprctl binds` -- the manifest is
+-- how this side of the desktop tells the other what these binds are for.
+--
+-- Never raises. A read-only or missing state directory costs the categories,
+-- which the shell falls back from, and must never cost the keymap.
+local function write_categories()
+    local state_home = os.getenv("XDG_STATE_HOME")
+    if state_home == nil or state_home == "" then
+        local home = os.getenv("HOME")
+        if home == nil or home == "" then
+            return
+        end
+        state_home = home .. "/.local/state"
+    end
+
+    local parts = {}
+    for chord, name in pairs(categories) do
+        -- Chords and category names are both from this file, so the only
+        -- escaping that can matter is the quote character itself.
+        parts[#parts + 1] = string.format('%q:%q', chord, name)
+    end
+    table.sort(parts)
+
+    local path = state_home .. "/panama/keybind-categories.json"
+    os.execute("mkdir -p " .. string.format("%q", state_home .. "/panama"))
+    local file = io.open(path, "w")
+    if file == nil then
+        return
+    end
+    file:write("{" .. table.concat(parts, ",") .. "}\n")
+    file:close()
+end
+
+-- SUPER opens a new one. SUPER+ALT goes to the one you already have.
+--
+-- That order matters and was chosen deliberately after trying the reverse.
+-- Making the plain key focus an existing window reads well in a demo and is
+-- what macOS does, but it makes "give me another terminal" the awkward case --
+-- and on a tiling desktop, opening a second terminal beside the first is not
+-- an edge case, it is the normal way to work. So the plain key keeps doing
+-- what it has always done, and the modifier is the new capability rather than
+-- a tax on the old one.
+--
+-- ALT rather than SHIFT because SUPER+SHIFT is already the window-manipulation
+-- space: Files, Neovim and Settings would have collided with Focus session,
+-- Taller and Shorter, and breaking two keys out of the eight-key resize set to
+-- make room is a worse trade than borrowing a modifier.
+--
+-- The go-to binds still launch when nothing is open. A key that silently does
+-- nothing is worse than one that does the obvious thing.
+--
+-- Patterns are regular expressions and are anchored. An unanchored "mail"
+-- would match gmail-notifier, and the go-to-mail key would raise somebody's
+-- notifier instead. Single-quoted for the shell so a backslash reaches the
+-- matcher rather than being eaten on the way.
+local function shell_quote(value)
+    return "'" .. value:gsub("'", "'\\''") .. "'"
+end
+
+local launcher_bin = "$HOME/.local/share/Panama/bin/panama-launch"
+
+local function go_to(class, command, title)
+    local parts = { launcher_bin, "--class", shell_quote(class) }
+    if title then
+        parts[#parts + 1] = "--title"
+        parts[#parts + 1] = shell_quote(title)
+    end
+    parts[#parts + 1] = "--"
+    parts[#parts + 1] = command
+    return table.concat(parts, " ")
+end
+
+category("Applications")
 bind(mod .. " + T", hl.dsp.exec_cmd(terminal), { description = "Terminal" })
 bind(mod .. " + N", hl.dsp.exec_cmd(editor), { description = "Neovim" })
 bind(mod .. " + W", hl.dsp.exec_cmd(browser), { description = "Browser" })
 bind(mod .. " + F", hl.dsp.exec_cmd(files), { description = "Files" })
 bind(mod .. " + C", hl.dsp.exec_cmd(calculator), { description = "Calculator" })
 bind(mod .. " + E", hl.dsp.exec_cmd(mail), { description = "Mail" })
+
+-- Go to the one already open, or start it if there is none.
+bind(mod .. " + ALT + T", hl.dsp.exec_cmd(go_to("^kitty$", terminal)),
+    { description = "Go to terminal" })
+bind(mod .. " + ALT + N", hl.dsp.exec_cmd(go_to("^kitty$", editor, "nvim")),
+    { description = "Go to Neovim" })
+bind(mod .. " + ALT + W", hl.dsp.exec_cmd(go_to("^helium", browser)),
+    { description = "Go to browser" })
+bind(mod .. " + ALT + F", hl.dsp.exec_cmd(go_to("^org\\.gnome\\.Nautilus$", files)),
+    { description = "Go to files" })
+bind(mod .. " + ALT + C", hl.dsp.exec_cmd(go_to("^org\\.gnome\\.Calculator$", calculator)),
+    { description = "Go to calculator" })
+bind(mod .. " + ALT + E", hl.dsp.exec_cmd(go_to("^org\\.mozilla\\.thunderbird", mail)),
+    { description = "Go to mail" })
 bind(mod .. " + I", hl.dsp.exec_cmd(settings), { description = "Settings" })
 bind("CTRL + SHIFT + Escape", hl.dsp.exec_cmd(sysmonitor), { description = "System monitor" })

 -- ── Launcher ────────────────────────────────────────────────────────────────
+category("Applications")
 -- All three keys open the same launcher, on purpose: SUPER+A and SUPER+R were
 -- the GNOME app-grid and run-dialog shortcuts, and SUPER+SPACE is here as a
 -- third option to settle on. Vicinae covers apps, calculator, files, clipboard,
@@ -101,6 +219,10 @@ bind(mod .. " + Space", hl.dsp.exec_cmd(launcher), { description = "Launcher" })
 -- application without dropping to a TTY. Depends on nothing but wofi itself.
 bind(mod .. " + SHIFT + R", hl.dsp.exec_cmd("wofi"), { description = "Fallback launcher" })

+-- Every shortcut, on one key. Slash because "what are the keys" is a question,
+-- and because it is the one punctuation key no other bind wants.
+bind(mod .. " + slash", hl.dsp.exec_cmd(qs("cheatsheet", "toggle")), { description = "Keyboard shortcuts" })
+
 -- Clipboard history and emoji, straight into the relevant launcher view.
 -- Deeplink form is the one from vicinae's own Hyprland quickstart.
 bind(mod .. " + V", hl.dsp.exec_cmd("vicinae vicinae://launch/clipboard/history"),
@@ -109,6 +231,7 @@ bind(mod .. " + Period", hl.dsp.exec_cmd("vicinae vicinae://launch/emoji/search"
    { description = "Emoji picker" })

 -- ── Shell surfaces (Quickshell) ─────────────────────────────────────────────
+category("Shell")
 -- SUPER+S was GNOME's quick settings; kept.
 bind(mod .. " + S", hl.dsp.exec_cmd(qs("quicksettings", "toggle")), { description = "Quick settings" })

@@ -140,7 +263,46 @@ bind(mod .. " + SHIFT + S", hl.dsp.exec_cmd(qs("screen-intelligence", "open")),
 -- Color picker: copies the hex under the cursor to the clipboard.
 bind(mod .. " + SHIFT + P", hl.dsp.exec_cmd("hyprpicker -a -f hex"), { description = "Color picker" })

+-- ── Magnifier ───────────────────────────────────────────────────────────────
+category("Shell")
+--
+-- The chords are NOT the obvious SUPER+=/-/0. SUPER+equal is already "Reset
+-- split" (Window management, below), and taking a daily tiling key away to
+-- give the magnifier the prettiest chord on the keyboard is the wrong trade.
+--
+-- SUPER+ALT is where they went instead, which is also where GNOME's magnifier
+-- lives: gsettings' magnifier-zoom-in / magnifier-zoom-out ship as
+-- <Alt><Super>= and <Alt><Super>-, so this is the shortcut the machine this
+-- desktop replaced already had. SUPER+ALT+0 -- free; the workspace digits are
+-- plain ALT -- resets to 1.00 ×, reading as "back to zero magnification".
+--
+-- These go THROUGH the shell rather than calling `hyprctl keyword
+-- cursor:zoom_factor` directly. Setting the compositor option behind Panama's
+-- back would leave the stored preference and the Magnifier slider claiming a
+-- magnification that is not the one on screen; the IPC call commits through
+-- the same verified-preference path the slider uses, so the store, the
+-- compositor and the settings page can never disagree. It also posts the OSD,
+-- which is the only way to see what the factor now is with the pointer
+-- somewhere else entirely.
+--
+-- Not `repeating`: the step is multiplicative (×1.25), so a held key repeating
+-- at the keyboard rate would arrive at the 5.00 × ceiling in about a tenth of
+-- a second. One press, one step.
+--
+-- Written as literal chords rather than `mod .. " + ALT + ..."` (as
+-- "SUPER + Backspace" already is, above) because these three are the most
+-- collision-prone binds in the file -- they were placed around one -- and a
+-- literal is the form both the duplicate-chord check and the settings page's
+-- chord display can actually read.
+bind("SUPER + ALT + equal", hl.dsp.exec_cmd(qs("accessibility", "zoom in")),
+    { description = "Zoom in" })
+bind("SUPER + ALT + minus", hl.dsp.exec_cmd(qs("accessibility", "zoom out")),
+    { description = "Zoom out" })
+bind("SUPER + ALT + 0", hl.dsp.exec_cmd(qs("accessibility", "zoom reset")),
+    { description = "Reset zoom" })
+
 -- ── Window management ───────────────────────────────────────────────────────
+category("Windows")
 bind(mod .. " + Q", hl.dsp.window.close(), { description = "Close window" })
 bind(mod .. " + U", hl.dsp.window.fullscreen({ mode = "fullscreen" }), { description = "Fullscreen" })

@@ -232,6 +394,7 @@ bind(mod .. " + mouse:272", hl.dsp.window.drag(), { mouse = true, description =
 bind(mod .. " + mouse:273", hl.dsp.window.resize(), { mouse = true, description = "Resize window with pointer" })

 -- ── Workspaces ──────────────────────────────────────────────────────────────
+category("Workspaces")
 -- ALT is the workspace modifier, matching the GNOME setup.
 --
 -- Plain relative selectors ("+1" / "-1") reproduce GNOME's dynamic workspaces:
@@ -284,12 +447,15 @@ bind(mod .. " + X", hl.dsp.workspace.toggle_special("scratch"), { description =
 bind(mod .. " + SHIFT + X", hl.dsp.window.move({ workspace = "special:scratch" }), { description = "Minimize to scratchpad" })

 -- ── Session ─────────────────────────────────────────────────────────────────
+category("Session")
 -- GNOME's lock was SUPER+L, which is "focus right" here, so lock moves to
 -- CTRL+ALT+L -- the other binding most people already have in muscle memory.
 bind("CTRL + ALT + L", hl.dsp.exec_cmd("loginctl lock-session"), { description = "Lock" })
+bind("SUPER + Backspace", hl.dsp.exec_cmd("loginctl lock-session"), { description = "Lock" })
 bind("CTRL + ALT + Delete", hl.dsp.exec_cmd(qs("powermenu", "toggle")), { description = "Power menu" })

 -- ── Media and volume ────────────────────────────────────────────────────────
+category("Media & hardware")
 -- locked = true keeps these working on the lock screen, as they do in GNOME.
 -- 6% steps match the GNOME volume-step setting.
 bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd(osd("volume up 6")), { locked = true, repeating = true , description = "Volume up" })
@@ -298,6 +464,7 @@ bind("XF86AudioMute", hl.dsp.exec_cmd(osd("volume toggle")), { locked = true , d
 bind("XF86AudioMicMute", hl.dsp.exec_cmd(osd("microphone toggle")), { locked = true , description = "Mute microphone" })

 -- ── Dictation ───────────────────────────────────────────────────────────────
+category("Shell")
 --
 -- Hold to talk, exactly like push-to-talk anywhere else: the mic is open only
 -- while the key is down, so it cannot be left listening by forgetting about it.
@@ -317,6 +484,10 @@ bind(mod .. " + D", hl.dsp.exec_cmd(dictate("stop")),
 bind(mod .. " + SHIFT + D", hl.dsp.exec_cmd(dictate("cancel")),
    { description = "Cancel dictation" })

+-- Back to media: the dictation binds sit here for historical reasons, and the
+-- category has to be set again or everything below inherits theirs.
+category("Media & hardware")
+
 -- Fine-grained steps, matching GNOME's shift/alt volume modifiers.
 bind("SHIFT + XF86AudioRaiseVolume", hl.dsp.exec_cmd(osd("volume up 1")), { locked = true, repeating = true , description = "Volume up (fine)" })
 bind("SHIFT + XF86AudioLowerVolume", hl.dsp.exec_cmd(osd("volume down 1")), { locked = true, repeating = true , description = "Volume down (fine)" })
@@ -330,6 +501,72 @@ bind("XF86AudioStop", hl.dsp.exec_cmd(osd("media stop")), { locked = true , desc
 bind("XF86MonBrightnessUp", hl.dsp.exec_cmd(osd("brightness up 5")), { locked = true, repeating = true , description = "Brightness up" })
 bind("XF86MonBrightnessDown", hl.dsp.exec_cmd(osd("brightness down 5")), { locked = true, repeating = true , description = "Brightness down" })

+-- Airplane mode. The Framework's F10 emits exactly this keysym, and for a
+-- while it emitted it into silence. panama-osd owns the toggle so the OSD
+-- can say which way it went.
+bind("XF86RFKill", hl.dsp.exec_cmd(osd("airplane toggle")), { locked = true, description = "Airplane mode" })
+
+-- F9 on the same row. GNOME shows a display-switching OSD here; until
+-- mirroring exists (DESKTOP-PARITY gap), the honest action is the page where
+-- displays are actually arranged.
+bind("XF86Display", hl.dsp.exec_cmd("qs ipc call settings page displays"), { description = "Display settings" })
+
+-- ── The power button ────────────────────────────────────────────────────────
+category("Media & hardware")
+--
+-- logind is told to ignore the power key (config/copy ships the drop-in) so a
+-- stray press is a question, not an instant poweroff. That makes what the
+-- question IS Panama's to choose, and `powerButtonAction` is where the choice
+-- is recorded. Until the next boot after that drop-in lands, logind still acts
+-- on the key; this bind costs nothing extra then.
+--
+-- The branch runs ON EVERY PRESS rather than here at config time.
+--
+-- A config-time branch would be shorter -- `prefs.get` and four `if`s -- and it
+-- would also make this the one control on the Power page that does nothing
+-- until the compositor is reloaded. Every other setting in Panama applies as
+-- you change it, and a power button that ignores what the settings app says it
+-- does is a worse thing to ship than a long command string. So the bind is a
+-- `case` over what the settings file says at the moment the key goes down.
+--
+-- Everything that can go wrong lands on the shipped default: no jq, no file, a
+-- truncated file, or a value nobody recognises all fall through to `*)` and
+-- open the menu. The failure direction is "the power button opens a menu",
+-- never "the power button does something you did not ask for".
+--
+-- Powering off goes THROUGH the menu with Power Off pre-armed rather than
+-- calling `systemctl poweroff` here. The menu's two-press confirm is what
+-- stands between a pocketed key and an unsaved afternoon, and a direct
+-- poweroff would quietly throw it away -- so a person who picks "Powers off"
+-- gets a fast poweroff, not an unguarded one.
+local power_button = {
+    menu     = qs("powermenu", "toggle"),
+    suspend  = "systemctl suspend",
+    poweroff = qs("powermenu", "open") .. " poweroff",
+    nothing  = ":",
+}
+
+local power_button_command = table.concat({
+    [[case "$(jq -r '.powerButtonAction // empty' "${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json" 2>/dev/null)" in]],
+    "suspend) " .. power_button.suspend .. " ;;",
+    "poweroff) " .. power_button.poweroff .. " ;;",
+    "nothing) " .. power_button.nothing .. " ;;",
+    "*) " .. power_button.menu .. " ;;",
+    "esac",
+}, " ")
+
+bind("XF86PowerOff", hl.dsp.exec_cmd(power_button_command),
+    { locked = true, description = "Power button" })
+
+-- The lid, as a switch rather than a key. Closing a docked lid turns the
+-- internal panel off so nothing renders inside a closed shell and no
+-- workspace strands on an invisible output; opening it turns the panel back
+-- on. panama-lid owns the decision -- undocked machines suspend via logind
+-- before this matters, and the guard's inhibitor handles staying awake.
+bind("switch:on:Lid Switch", hl.dsp.exec_cmd(lid("close")), { locked = true, description = "Lid closed" })
+bind("switch:off:Lid Switch", hl.dsp.exec_cmd(lid("open")), { locked = true, description = "Lid opened" })
+
+category("Applications")
 -- Hardware keys GNOME mapped that have obvious equivalents.
 bind("XF86Tools", hl.dsp.exec_cmd(settings), { description = "Settings" })
 bind("XF86Calculator", hl.dsp.exec_cmd(calculator), { description = "Calculator" })
@@ -338,4 +575,52 @@ bind("XF86WWW", hl.dsp.exec_cmd(browser), { description = "Browser" })
 bind("XF86Mail", hl.dsp.exec_cmd(mail), { description = "Mail" })
 bind("XF86Search", hl.dsp.exec_cmd(launcher), { description = "Launcher" })

+-- ── Custom shortcuts ────────────────────────────────────────────────────────
+--
+-- Shortcuts the user invented, from `customBinds` in settings.json. Each entry
+-- is { chord, kind, target, label } -- data, never a command. actions.lua turns
+-- the kind/target pair into a dispatcher through whitelist tables; an entry it
+-- does not recognise resolves to nil and is silently not emitted.
+--
+-- Emitted LAST, and through hl.bind rather than the `bind` wrapper above. Two
+-- separate reasons, both about keeping the two rebinding mechanisms apart:
+--
+--   * `keybindOverrides` is keyed by a SHIPPED chord. A custom bind has no
+--     shipped chord -- it is rebound by rewriting its own entry -- so putting
+--     one through `bind` would let an override for some shipped key silently
+--     move a custom one that happened to share a chord.
+--   * last means a custom chord that collides with a shipped one loses, which
+--     is checked explicitly below rather than left to Hyprland's ordering.
+--
+-- Settings prevents a collision upstream; this is the second lock, because the
+-- file is hand-editable and losing a shipped key to a typo is not acceptable.
+category("Custom")
+
+local function custom_bind(chord, dispatcher, label)
+    categories[chord] = current_category
+    return hl.bind(chord, dispatcher, { description = label })
+end
+
+for _, entry in ipairs(prefs.get("customBinds", {})) do
+    if type(entry) == "table" then
+        local chord = entry.chord
+        local label = entry.label
+
+        -- A description is not decoration: keybinds-contract fails a build
+        -- with a description-less bind, and the cheatsheet and Shortcuts page
+        -- both list what they find. A nameless shortcut is unfindable.
+        if valid_chord(chord)
+            and type(label) == "string" and label ~= ""
+            and categories[chord] == nil
+        then
+            local dispatcher = actions.dispatcher(entry)
+            if dispatcher ~= nil then
+                custom_bind(chord, dispatcher, label)
+            end
+        end
+    end
+end
+
+write_categories()
+
 return true
@@ -14,18 +14,17 @@

 local prefs = require("prefs")

-- Mirrors config/Theme.qml's `accents` map. Lua has no import path into a QML
-- singleton, so the hex pairs are restated here -- just the four hex strings
-- each named accent needs, not the labels, which stay UI-only.
-local accents = {
+-- The eight accents, from config/palette.json -- the one place they are
+-- written down for everything outside QML. They used to be restated here,
+-- which made adding a ninth accent a five-file edit; the file that got
+-- forgotten was always the one that fails silently.
+--
+-- Falls back to the shipped blue pair if the palette cannot be read, for the
+-- same reason prefs never raises: a missing file costs the accent colour, not
+-- the compositor config.
+local palette = prefs.readJson(os.getenv("HOME") .. "/.config/quickshell/config/palette.json")
+local accents = palette.accents or {
    blue = { dark = "82aaff", darkSecondary = "b172b0", light = "2e7de9", lightSecondary = "9854f1" },
-    orchid = { dark = "c099ff", darkSecondary = "fca7ea", light = "7847bd", lightSecondary = "9854f1" },
-    teal   = { dark = "86e1fc", darkSecondary = "82aaff", light = "007197", lightSecondary = "2e7de9" },
-    green  = { dark = "c3e88d", darkSecondary = "86e1fc", light = "587539", lightSecondary = "007197" },
-    amber  = { dark = "ffc777", darkSecondary = "ff966c", light = "8c6c3e", lightSecondary = "b15c00" },
-    orange = { dark = "ff966c", darkSecondary = "ff757f", light = "b15c00", lightSecondary = "c64343" },
-    rose   = { dark = "ff757f", darkSecondary = "c099ff", light = "f52a65", lightSecondary = "9854f1" },
-    slate  = { dark = "828bb8", darkSecondary = "82aaff", light = "6172b0", lightSecondary = "2e7de9" },
 }

 -- The accent pair a fresh session or `hyprctl reload` starts from.
@@ -38,6 +37,53 @@ local accentPair = accents[prefs.get("accentName", "blue")] or accents.blue
 local accentStart = accentScheme == "light" and accentPair.light or accentPair.dark
 local accentEnd = accentScheme == "light" and accentPair.lightSecondary or accentPair.darkSecondary

+-- ── Color filters ───────────────────────────────────────────────────────────
+--
+-- Grayscale and three color-blindness corrections, as end-of-pipe screen
+-- shaders. Hyprland composites the desktop and then runs one fragment shader
+-- over the result, so a filter here covers every window, the shell, the cursor
+-- and video alike -- which is the only way a filter is honest.
+--
+-- The PREFERENCE is the enum, not the path. That split is deliberate: storing
+-- the path would put a filesystem location a person can edit into the value
+-- that becomes `decoration:screen_shader`, and it would make the stored value
+-- disagree with what hyprctl reports back (which is the path), failing the
+-- schema shape and write-sweep contracts. So PreferenceSchema's colorFilter
+-- entry carries no `hypr:` block, and the enum→path mapping is written twice
+-- on purpose: here, for reloads and for the moment before the shell starts,
+-- and in services/SystemSettings.qml's applyColorFilter for the live apply.
+-- The two lists have to be edited together.
+--
+-- "none" and anything unrecognised both produce the empty string, which is
+-- what Hyprland reads as "no shader" -- and is the value it needs to be given
+-- to turn one OFF, since there is no way to unset the option.
+local shaderDir = (function()
+    local configHome = os.getenv("XDG_CONFIG_HOME")
+    if configHome == nil or configHome == "" then
+        local home = os.getenv("HOME")
+        if home == nil or home == "" then
+            return nil
+        end
+        configHome = home .. "/.config"
+    end
+    return configHome .. "/hypr/shaders"
+end)()
+
+local colorFilters = {
+    grayscale    = "grayscale.frag",
+    protanopia   = "protanopia.frag",
+    deuteranopia = "deuteranopia.frag",
+    tritanopia   = "tritanopia.frag",
+}
+
+local colorFilterShader = ""
+do
+    local file = colorFilters[prefs.get("colorFilter", "none")]
+    if file ~= nil and shaderDir ~= nil then
+        colorFilterShader = shaderDir .. "/" .. file
+    end
+end
+
 hl.config({
    general = {
        gaps_in  = prefs.get("gapsIn", 5),
@@ -69,10 +115,10 @@ hl.config({
        -- Harmless on its own; tearing only happens where a rule opts in.
        allow_tearing = true,

-        layout = "dwindle",
+        layout = prefs.get("windowLayout", "dwindle"),

        snap = {
-            enabled      = true,
+            enabled      = prefs.get("windowSnapping", true),
            window_gap   = prefs.getInt("snapWindowGap", 10),
            monitor_gap  = prefs.getInt("snapMonitorGap", 10),
            respect_gaps = prefs.get("snapRespectGaps", false),
@@ -89,6 +135,10 @@ hl.config({
        fullscreen_opacity = prefs.get("fullscreenOpacity", 1.0),
        inactive_opacity = prefs.get("inactiveOpacity", 1.0),

+        -- Accessibility: dim every window but the focused one.
+        dim_inactive = prefs.get("dimInactive", false),
+        dim_strength = prefs.get("dimStrength", 0.5),
+
        blur = {
            enabled = prefs.get("blurEnabled", true),
            size    = prefs.get("blurSize", 8),
@@ -142,6 +192,11 @@ hl.config({

        -- Off: costs real frame time and reads as smeary on a 60Hz panel.
        motion_blur = { enabled = false },
+
+        -- The accessibility color filter, resolved above. Empty when off, and
+        -- empty costs nothing: Hyprland skips the pass entirely rather than
+        -- running an identity shader.
+        screen_shader = colorFilterShader,
    },

    animations = { enabled = prefs.get("animationsEnabled", true) },
@@ -151,6 +206,7 @@ hl.config({
        -- to how the Forge extension behaved on GNOME.
        preserve_split = prefs.get("preserveSplit", true),
        smart_resizing = true,
+        force_split    = prefs.getInt("forceSplit", 0),
    },

    -- Only in effect when the tiling layout is "master". Panama ships dwindle,
@@ -194,7 +250,11 @@ hl.config({
        allow_session_lock_restore = true,

        -- Don't let apps steal focus by shouting; matches GNOME's behavior.
-        focus_on_activate = false,
+        focus_on_activate = prefs.get("focusOnActivate", false),
+
+        -- Whether pointing at another monitor is enough to move focus there,
+        -- or it takes a click. GNOME moves on pointer; both are offered.
+        mouse_move_focuses_monitor = prefs.get("mouseMoveFocusesMonitor", true),

        -- Window swallowing: a terminal hides itself while a graphical
        -- application launched from it is open, and comes back when that
@@ -238,6 +298,10 @@ hl.config({

        -- Fade the cursor out after 4s of no movement, like GNOME does.
        inactive_timeout = prefs.get("cursorInactiveTimeout", 4),
+
+        -- The accessibility magnifier. 1.0 = off.
+        zoom_factor = prefs.get("magnifierFactor", 1.0),
+        zoom_rigid  = prefs.get("magnifierRigid", false),
    },

    ecosystem = {
@@ -1,7 +1,7 @@
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Monitors
 --
-- Kuycon P20 on DP-2: 4500x3000 @ 60Hz, 1.5x fractional scale.
+-- Kuycon P20 (matched by description): 4500x3000 @ 60Hz, 1.5x fractional scale.
 -- 4500/1.5 = 3000 and 3000/1.5 = 2000, both integers, so this is a "clean"
 -- fractional scale and Hyprland will not complain.
 --
@@ -13,8 +13,9 @@
 -- than an HDR desktop, the desktop runs SDR at 10-bit and HDR is handed to
 -- fullscreen games only, via render.cm_auto_hdr in looks.lua.
 --
-- To try full-time HDR anyway, set cm = "hdr" below (or override it in
-- overrides.lua) and read the notes in that file first.
+-- To try full-time HDR anyway, set shipped_cm = "hdr" below (or pick HDR for
+-- this display in Settings, which saves it as the display's colorProfile and
+-- wins over the shipped value) and read the notes in overrides.lua first.
 -- ─────────────────────────────────────────────────────────────────────────────

 local prefs = require("prefs")
@@ -23,12 +24,21 @@ local prefs = require("prefs")
 --   { ["DP-2"] = {
 --       mode = "3840x2160@60", scale = 2, transform = 0,
 --       x = 0, y = 0, primary = true,
+--       vrrMode = -1, colorProfile = "auto", bitdepth = 10,
+--       sdrBrightness = 1, sdrSaturation = 1, mirrorOf = "",
 --   } }
 --
-- Only mode, scale, and transform are read. Color management and bit depth
-- stay here, because those are the settings with a documented reason attached
-- (see the header) rather than preferences, and a settings page has no way to
-- explain the screencopy tradeoff at the moment you would be changing it.
+-- The fields past `primary` are optional: records written before they existed
+-- carry none of them, and the shipped values below stand instead. That is the
+-- relationship in both directions -- what is written here is what a saved
+-- record inherits, and what Settings saves is what overrides it, so the two
+-- stop fighting over the same monitor rule.
+--
+-- Geometry and colour fail differently on purpose. A half-written position is
+-- refused outright (below), because guessing one can strand an output where
+-- nothing can reach it. An unreadable colour, VRR or mirror value is dropped
+-- on its own and the shipped default stands: the worst it costs is a wrong
+-- shade, and taking the whole record down with it would cost the arrangement.
 local displays = prefs.get("displays", {})
 if type(displays) ~= "table" then
    displays = {}
@@ -125,45 +135,132 @@ local function display_position(entry, fallback)
    return fallback
 end

-local shipped_mode = "4500x3000@60"
-local shipped_scale = 1.5
-local shipped_transform = 0
-local dp2 = display_entry("DP-2")
+local color_profiles = { auto = true, srgb = true, wide = true, hdr = true }

-hl.monitor({
-    output   = "DP-2",
-    mode     = dp2 and dp2.mode or shipped_mode,
-    position = display_position(dp2, "0x0"),
-    scale    = dp2 and dp2.scale or shipped_scale,
-    transform = dp2 and dp2.transform or shipped_transform,
+local function color_profile(entry, fallback)
+    local value = entry ~= nil and entry.colorProfile or nil
+    if type(value) == "string" and color_profiles[value] then
+        return value
+    end
+    return fallback
+end

-    -- 10-bit output. 4500x3000@60 at 10bpc is ~24 Gbps, right at the edge of
-    -- DP 1.4 HBR3, so this relies on DSC. If the display fails to light up or
-    -- falls back to a lower mode, drop this line first.
-    bitdepth = 10,
+local function bitdepth_value(entry, fallback)
+    local value = entry ~= nil and entry.bitdepth or nil
+    if value == 8 or value == 10 then
+        return value
+    end
+    return fallback
+end

-    -- "auto" = sRGB at 8bpc, wide gamut at 10bpc. Not HDR; see header.
-    cm = "auto",
-})
+-- -1 means the display follows the global misc.vrr policy, which is said by
+-- leaving the key out. 3 is the global policy's own value and not a per-display
+-- choice, so it is not accepted here either.
+local function vrr_value(entry)
+    local value = entry ~= nil and entry.vrrMode or nil
+    if type(value) ~= "number" or value ~= math.floor(value)
+        or value < 0 or value > 2 then
+        return nil
+    end
+    return value
+end

-- Other connected outputs use the same validated per-output store. They keep
-- automatic placement and the compositor's normal color policy; DP-2 alone
-- carries the panel-specific 10-bit policy documented above.
+-- Neutral is 1.0, and the neutral value is left out rather than written: a rule
+-- that names it pins the display to it, which is not the same as leaving the
+-- trim alone.
+local function sdr_value(value, minimum, maximum)
+    if type(value) ~= "number" or value ~= value
+        or value < minimum or value > maximum
+        or math.abs(value - 1) < 0.001 then
+        return nil
+    end
+    return value
+end
+
+-- A mirror needs a target that is not itself and not another mirror -- Hyprland
+-- has no chain to follow -- and the primary may not mirror at all, since the
+-- arrangement is anchored on it.
+local function mirror_value(entry, output)
+    local value = entry ~= nil and entry.mirrorOf or nil
+    if type(value) ~= "string" or value == "" or value == output
+        or value:match("^[%w_.-]+$") == nil
+        or entry.primary == true then
+        return nil
+    end
+    local target = displays[value]
+    if type(target) == "table" and type(target.mirrorOf) == "string"
+        and target.mirrorOf ~= "" then
+        return nil
+    end
+    return value
+end
+
+-- Colour, VRR and mirroring layered onto a rule that already carries
+-- mode/position/scale/transform. A monitor rule replaces the previous rule for
+-- that output whole, so the shipped defaults are passed in here rather than
+-- written in a rule of their own. `connector` is the output name the record was
+-- saved under, which is not always the rule's own output: the Kuycon rule
+-- matches by description.
+local function with_display_fields(rule, entry, connector, default_bitdepth, default_cm)
+    rule.bitdepth = bitdepth_value(entry, default_bitdepth)
+    rule.cm = color_profile(entry, default_cm)
+    rule.vrr = vrr_value(entry)
+    rule.sdrbrightness = entry ~= nil and sdr_value(entry.sdrBrightness, 0.8, 2.0) or nil
+    rule.sdrsaturation = entry ~= nil and sdr_value(entry.sdrSaturation, 0.8, 1.2) or nil
+
+    -- A mirror shows its target's picture in its target's place, so the saved
+    -- position is not the compositor's to honour or ours to ask for.
+    local mirror = mirror_value(entry, connector)
+    if mirror ~= nil then
+        rule.mirror = mirror
+        rule.position = "auto"
+    end
+    return rule
+end
+
+-- Every connected output uses the same validated per-output store. Automatic
+-- placement and the compositor's normal color policy unless the entry says
+-- otherwise.
 for output, _ in pairs(displays) do
-    if output ~= "DP-2" then
    local entry = display_entry(output)
    if entry ~= nil then
-            hl.monitor({
+        hl.monitor(with_display_fields({
            output = output,
            mode = entry.mode,
            position = display_position(entry, "auto"),
            scale = entry.scale,
            transform = entry.transform,
-            })
-        end
+        }, entry, output, nil, nil))
    end
 end

+-- The Kuycon P20, matched by what it is rather than where it is plugged in.
+-- This used to be a rule for connector DP-2 outright, which handed the panel's
+-- 4500x3000 mode and 1.5 scale to whatever monitor a stranger's machine had on
+-- its most common DisplayPort connector. Emitted after the prefs loop so a
+-- saved entry for its connector still carries the mode/scale/position, while
+-- this rule holds the shipped defaults and the panel-specific color policy.
+local shipped_mode = "4500x3000@60"
+local shipped_scale = 1.5
+local shipped_transform = 0
+
+-- 10-bit output. 4500x3000@60 at 10bpc is ~24 Gbps, right at the edge of DP 1.4
+-- HBR3, so this relies on DSC. If the display fails to light up or falls back to
+-- a lower mode, drop this to 8 first.
+local shipped_bitdepth = 10
+
+-- "auto" = sRGB at 8bpc, wide gamut at 10bpc. Not HDR; see header.
+local shipped_cm = "auto"
+
+local kuycon = display_entry("DP-2")
+hl.monitor(with_display_fields({
+    output   = "desc:GVT Kuycon P20",
+    mode     = kuycon and kuycon.mode or shipped_mode,
+    position = display_position(kuycon, "0x0"),
+    scale    = kuycon and kuycon.scale or shipped_scale,
+    transform = kuycon and kuycon.transform or shipped_transform,
+}, kuycon, "DP-2", shipped_bitdepth, shipped_cm))
+
 -- Any monitor not named above: sane defaults rather than nothing.
 hl.monitor({
    output   = "",
@@ -190,18 +287,25 @@ hl.monitor({
 -- empty monitor leaves the previous binding in place. So the config is the only
 -- honest source, and applying a change is a reload.
 if prefs.get("workspacesOnPrimaryOnly", false) == true then
-    local primary = nil
-    for output, entry in pairs(displays) do
-        if type(entry) == "table" and entry.primary == true
-            and type(output) == "string" and output:match("^[%w_.-]+$") ~= nil then
-            primary = output
-            break
+    -- Only a record display_entry accepts counts. A half-written entry is one
+    -- the monitor rules above already refuse, so pinning ten workspaces to it on
+    -- the strength of a `primary` flag nothing else trusts would put them on a
+    -- screen that never got a rule of its own.
+    local primaries = {}
+    for output, _ in pairs(displays) do
+        local entry = display_entry(output)
+        if entry ~= nil and entry.primary == true then
+            primaries[#primaries + 1] = output
        end
    end

    -- Without a primary there is nothing to pin to, and guessing one would move
-    -- every workspace onto whichever screen happened to sort first.
-    if primary ~= nil then
+    -- every workspace onto whichever screen happened to sort first. Two records
+    -- both claiming primary is the same problem wearing a different hat: pairs()
+    -- has no order, so picking one of them would pin the workspaces to a
+    -- different screen from one reload to the next. Neither case guesses.
+    if #primaries == 1 then
+        local primary = primaries[1]
        for i = 1, 10 do
            hl.workspace_rule({ workspace = tostring(i), monitor = primary })
        end
@@ -244,6 +244,33 @@ function prefs.getInt(key, fallback)
    return math.floor(value + 0.5)
 end

+-- Read and decode any JSON file, using the same never-raise parser the
+-- settings store uses. Returns an empty table for a file that is missing,
+-- empty, or malformed, so a caller can index the result without checking.
+--
+-- Exists so config/palette.json can be read by looks.lua rather than the eight
+-- accents being written out a second time in Lua. A bad palette costs the
+-- accent colours, never the compositor config.
+function prefs.readJson(path)
+    if type(path) ~= "string" or path == "" then
+        return {}
+    end
+    local file = io.open(path, "r")
+    if not file then
+        return {}
+    end
+    local text = file:read("*a")
+    file:close()
+    if not text or text:match("^%s*$") then
+        return {}
+    end
+    local ok, parsed = pcall(decode, text)
+    if not ok or type(parsed) ~= "table" then
+        return {}
+    end
+    return parsed
+end
+
 -- True when a settings file was actually read. Useful from overrides.lua.
 function prefs.loaded()
    return next(values) ~= nil
@@ -9,6 +9,8 @@
 -- to invert it.
 -- ─────────────────────────────────────────────────────────────────────────────

+local prefs = require("prefs")
+
 -- ── Upstream sanity rules ───────────────────────────────────────────────────
 hl.window_rule({
    name  = "suppress-maximize-events",
@@ -136,6 +138,97 @@ hl.window_rule({
    no_dim  = true,
 })

+-- ── Per-application rules the user wrote ────────────────────────────────────
+--
+-- `windowRules` in settings.json, edited from Settings' Windows page. Each
+-- entry is data and nothing else:
+--
+--   { class, label, float, center, size = {w, h}, workspace, noAnim, game,
+--     noDim, pin }
+--
+-- `class` is matched LITERALLY. Hyprland matches with RE2, so a class typed
+-- into a text field is a regular expression unless something escapes it -- and
+-- "org.gnome.Files" as a pattern also matches "orgxgnomexFiles", while a
+-- half-typed "(" is a pattern error rather than a rule that matches nothing.
+-- Escaped and anchored here, so what the user typed is what gets matched.
+--
+-- Emitted AFTER the shipped rules and deliberately WITHOUT a name. Hyprland
+-- evaluates every named rule before every anonymous one, so a named user rule
+-- would silently outrank the anonymous shipped rules above it -- the opposite
+-- of the intended precedence. Anonymous, last, is what "the user's rule wins"
+-- actually means here.
+--
+-- An entry that fails any check is skipped whole rather than emitted with the
+-- bad field dropped: a rule that half-applies is harder to understand than one
+-- that is not there, and the settings page can see the same thing is wrong.
+
+local function escape_regex(value)
+    return (value:gsub("[%^%$%(%)%%%.%[%]%*%+%-%?%{%}%|\\]", "\\%0"))
+end
+
+-- The shell's own surfaces are layers, not windows -- but Quickshell's helper
+-- windows are not, and a rule that floats or moves one of them would be a user
+-- breaking their own desktop from the Windows page. Refused at both ends; this
+-- is the end that matters, because the file is hand-editable.
+local function reserved_class(class)
+    local lowered = class:lower()
+    return lowered:match("^quickshell") ~= nil or lowered:match("^qs%-") ~= nil
+end
+
+local function positive_integer(value, low, high)
+    if type(value) ~= "number" or value ~= math.floor(value) then
+        return nil
+    end
+    if value < low or value > high then
+        return nil
+    end
+    return value
+end
+
+for _, entry in ipairs(prefs.get("windowRules", {})) do
+    if type(entry) == "table" and type(entry.class) == "string" then
+        local class = entry.class
+        local rule = nil
+
+        if #class >= 1 and #class <= 128 and not reserved_class(class) then
+            rule = { match = { class = "^" .. escape_regex(class) .. "$" } }
+
+            if entry.float   == true then rule.float   = true end
+            if entry.center  == true then rule.center  = true end
+            if entry.noAnim  == true then rule.no_anim = true end
+            if entry.noDim   == true then rule.no_dim  = true end
+            if entry.pin     == true then rule.pin     = true end
+            -- The keystone the gaming rules above use: misc.vrr,
+            -- render.direct_scanout and cursor.no_break_fs_vrr all key off it.
+            if entry.game    == true then rule.content = "game" end
+
+            if entry.size ~= nil then
+                local size = entry.size
+                local width  = type(size) == "table" and positive_integer(size[1], 50, 10000) or nil
+                local height = type(size) == "table" and positive_integer(size[2], 50, 10000) or nil
+                if width == nil or height == nil then
+                    rule = nil
+                else
+                    rule.size = { width, height }
+                end
+            end
+
+            if rule ~= nil and entry.workspace ~= nil then
+                local workspace = positive_integer(entry.workspace, 1, 10)
+                if workspace == nil then
+                    rule = nil
+                else
+                    rule.workspace = workspace
+                end
+            end
+        end
+
+        if rule ~= nil then
+            hl.window_rule(rule)
+        end
+    end
+end
+
 -- ── Workspace rules ─────────────────────────────────────────────────────────
 -- Deliberately NO "smart gaps".
 --
@@ -159,6 +252,11 @@ hl.layer_rule({
    name  = "qs-dock",
    match = { namespace = "^qs-dock$" },
    blur         = true,
+    -- The dock's context menu and its window previews are xdg-popups of this
+    -- surface, not layers of their own, so they are only blurred if the rule
+    -- says to blur the popups too. Without it they are flat panes over the
+    -- wallpaper while everything else on the desktop is glass.
+    blur_popups  = true,
    ignore_alpha = 0.3,
 })

@@ -0,0 +1,28 @@
+// Deuteranopia -- green-blind.
+//
+// Panama's accessibility color filters. Selected by the `colorFilter`
+// preference; hypr/looks.lua maps the enum to this path at config time and
+// services/SystemSettings.qml does the same live.
+//
+// Same family of matrices as protanopia.frag, weighted for the missing green
+// cone instead of the red one. See that file for why this is a correction
+// rather than a simulation, and for the column-major note.
+
+#version 300 es
+
+precision mediump float;
+in vec2 v_texcoord;
+layout(location = 0) out vec4 fragColor;
+uniform sampler2D tex;
+
+const mat3 deuteranopia = mat3(
+    0.625, 0.700, 0.000,
+    0.375, 0.300, 0.300,
+    0.000, 0.000, 0.700
+);
+
+void main() {
+    vec4 pixColor = texture(tex, v_texcoord);
+
+    fragColor = vec4(clamp(deuteranopia * pixColor.rgb, 0.0, 1.0), pixColor.a);
+}
@@ -0,0 +1,28 @@
+// Grayscale.
+//
+// Panama's accessibility color filters. Selected by the `colorFilter`
+// preference; hypr/looks.lua maps the enum to this path at config time and
+// services/SystemSettings.qml does the same live.
+//
+// Hyprland runs one fragment shader over the finished frame, so this covers
+// every window, the shell, video and the cursor alike.
+//
+// Rec. 709 luminance weights -- the same ones an SVG <feColorMatrix
+// type="saturate" values="0"> uses. A flat average would make reds and blues
+// far too bright and greens far too dark, because the eye does not weigh the
+// channels equally.
+
+#version 300 es
+
+precision mediump float;
+in vec2 v_texcoord;
+layout(location = 0) out vec4 fragColor;
+uniform sampler2D tex;
+
+void main() {
+    vec4 pixColor = texture(tex, v_texcoord);
+
+    float luminance = dot(pixColor.rgb, vec3(0.2126, 0.7152, 0.0722));
+
+    fragColor = vec4(vec3(luminance), pixColor.a);
+}
@@ -0,0 +1,33 @@
+// Protanopia -- red-blind.
+//
+// Panama's accessibility color filters. Selected by the `colorFilter`
+// preference; hypr/looks.lua maps the enum to this path at config time and
+// services/SystemSettings.qml does the same live.
+//
+// The matrix is the feColorMatrix set the mock uses, which is the widely
+// carried HCIRN-derived one: it redistributes the red channel into the two the
+// eye can still separate, so a red/green pair that was one colour becomes two
+// distinguishable ones. It is a CORRECTION, not a simulation -- the point is to
+// make the screen readable, not to show what protanopia looks like.
+//
+// Row-major here, column-major to GLSL: mat3 takes its arguments column by
+// column, so the transpose below is the matrix as written in the SVG.
+
+#version 300 es
+
+precision mediump float;
+in vec2 v_texcoord;
+layout(location = 0) out vec4 fragColor;
+uniform sampler2D tex;
+
+const mat3 protanopia = mat3(
+    0.567, 0.558, 0.000,
+    0.433, 0.442, 0.242,
+    0.000, 0.000, 0.758
+);
+
+void main() {
+    vec4 pixColor = texture(tex, v_texcoord);
+
+    fragColor = vec4(clamp(protanopia * pixColor.rgb, 0.0, 1.0), pixColor.a);
+}
@@ -0,0 +1,28 @@
+// Tritanopia -- blue-blind.
+//
+// Panama's accessibility color filters. Selected by the `colorFilter`
+// preference; hypr/looks.lua maps the enum to this path at config time and
+// services/SystemSettings.qml does the same live.
+//
+// Same family of matrices as protanopia.frag, weighted for the missing blue
+// cone. See that file for why this is a correction rather than a simulation,
+// and for the column-major note.
+
+#version 300 es
+
+precision mediump float;
+in vec2 v_texcoord;
+layout(location = 0) out vec4 fragColor;
+uniform sampler2D tex;
+
+const mat3 tritanopia = mat3(
+    0.950, 0.000, 0.000,
+    0.050, 0.433, 0.475,
+    0.000, 0.567, 0.525
+);
+
+void main() {
+    vec4 pixColor = texture(tex, v_texcoord);
+
+    fragColor = vec4(clamp(tritanopia * pixColor.rgb, 0.0, 1.0), pixColor.a);
+}
@@ -1,8 +1,11 @@
 # Tokyo Night Moon — the dark theme Panama ships.
 #
-# Extracted from kitty.conf so the two schemes can be swapped. kitty.conf
-# includes current-theme.conf, which Panama generates from the color scheme
-# setting; that generated file is gitignored because it is machine state.
+# Reference, not the source of the running colours. kitty.conf includes
+# current-theme.conf, which panama-theme-apps RENDERS from the active theme's
+# palette -- so any of the ten themes reaches the terminal, not only the two
+# Tokyo Nights. This file used to be copied into that one; it is kept because
+# it is a complete kitty theme somebody may want to include directly, and
+# because it is what Moon is supposed to look like.
 #
 # Live changes go through `kitty @ set-colors`, which is why kitty.conf enables
 # remote control. Without it a scheme change would only reach terminals opened
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Runs after `panama migrate` has applied repairs, and only when it applied at
+# least one. Takes no arguments.
+#
+# Useful when a machine keeps local state that a repair might have invalidated.
+#
+# Copy to ~/.config/panama/hooks/post-migrate and make it executable.
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Runs at the end of ./install, after every stage and after migrations.
+#
+# Takes no arguments. This is where per-machine setup goes that Panama should
+# not carry for everyone: a work laptop's VPN client, a private repository
+# somebody clones, a package only this machine wants.
+#
+# Copy to ~/.config/panama/hooks/post-upgrade and make it executable.
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Runs whenever the colour scheme or accent changes.
+#
+#   $1  scheme: "dark" or "light"
+#   $2  accent: blue, orchid, teal, green, amber, orange, rose or slate
+#
+# Copy to ~/.config/panama/hooks/theme-set and make it executable. Anything in
+# theme-set.d/ runs too, in sorted order, so several things can react without
+# fighting over one file.
+#
+# A failure here is reported and stepped over: it will never cost you a theme
+# change.
+
+scheme="$1"
+accent="$2"
+
+# For example: repaint something Panama does not know about.
+# printf 'set-theme %s\n' "$scheme" | nc -U "$HOME/.local/share/some-app/socket"
@@ -1,40 +1,79 @@
+// Headless theme editor, for accent-controls-contract.
+//
+// The two halves of the editor that write colour: the four wells
+// (ThemeEditorWells + ColorWell), which are the fast path and own hex
+// validation and the eyedropper, and the six HSV rows (AccentEditor), which
+// are the fine-tune behind a disclosure.
+//
+// AccentEditor commits on a debounce rather than per move, so `adjust` returns
+// what is *pending*, not what is stored -- the caller waits and reads `status`
+// again. That is the behaviour under test as much as the colour itself: a
+// slider that wrote on every move spent a whole drag in apply-and-verify round
+// trips and left the desktop repainting behind the pointer.
+
 import Quickshell
 import Quickshell.Io
 import QtQuick

+import qs.config
 import qs.modules.settings
 import qs.services

 ShellRoot {
    Item {
        width: 680
-        height: editor.implicitHeight
+        height: wells.implicitHeight + editor.implicitHeight
+
+        ThemeEditorWells {
+            id: wells
+            width: parent.width
+        }

        AccentEditor {
            id: editor
+            y: wells.implicitHeight
            width: parent.width
        }
-
-        ThemeProfilePicker {
-            width: parent.width
-            visible: false
-        }
-
-        AccentPicker {
-            width: parent.width
-            visible: false
-        }
    }

    IpcHandler {
        target: "accent-controls-test"

        function status(): string {
-            return JSON.stringify(ThemeProfiles.activeProfile);
+            return JSON.stringify({
+                id: ThemeProfiles.activeProfile.id,
+                name: ThemeProfiles.activeProfile.name,
+                scheme: ThemeProfiles.activeProfile.scheme,
+                accent: String(ThemeProfiles.activeProfile.accent),
+                secondary: String(ThemeProfiles.activeProfile.secondary),
+                shipped: ThemeProfiles.activeProfile.shipped === true,
+                accentName: String(DesktopPreferences.get("accentName")),
+                bg: String(ThemeProfiles.activePalette.bg),
+                fg: String(ThemeProfiles.activePalette.fg),
+                fgDim: String(ThemeProfiles.activePalette.fgDim),
+                pending: editor.pending !== null,
+                wellError: wells.lastError
+            });
        }

+        // Moves one HSV slider. The commit is debounced, so the answer is the
+        // pair the sliders are showing, not the stored one.
        function adjust(target: string, channel: string, ratio: real): string {
            editor.changeChannel(target, channel, ratio);
+            return JSON.stringify({
+                shown: { accent: editor.shownAccent, secondary: editor.shownSecondary },
+                pending: editor.pending !== null,
+                stored: {
+                    accent: String(ThemeProfiles.activeProfile.accent),
+                    secondary: String(ThemeProfiles.activeProfile.secondary)
+                }
+            });
+        }
+
+        // The one path every well takes -- typed hex, colour wheel and
+        // eyedropper all end here, so validation cannot differ between them.
+        function well(which: string, hex: string): string {
+            wells.apply(which, hex);
            return status();
        }
    }
@@ -75,6 +75,21 @@ ShellRoot {
        return AudioStreams.group(fixtureNodes, audioOutStreamFlag);
    }

+    // A throwaway two-stream group for the clamp cases. The shared fixture
+    // above is mutated by the volume and mute tests, and a clamp assertion that
+    // depended on which of those ran first would be worthless.
+    function clampFixture(): var {
+        return {
+            key: "clamp",
+            label: "Clamp",
+            icon: "audio-x-generic-symbolic",
+            nodes: [
+                { audio: { volume: 0.1, muted: true } },
+                { audio: { volume: 0.1, muted: true } }
+            ]
+        };
+    }
+
    IpcHandler {
        target: "application-volume-test"

@@ -115,6 +130,31 @@ ShellRoot {
            });
        }

+        // Over-amplification is a preference, so the ceiling is an argument
+        // rather than a constant -- this file stays Settings-free on purpose.
+        function clampVolume(): string {
+            const overAmp = clampFixture();
+            const overAmpChanged = AudioStreams.setVolume(overAmp, 1.4, 1.5);
+            const ceiling = clampFixture();
+            AudioStreams.setVolume(ceiling, 2.5, 1.5);
+            const defaultMax = clampFixture();
+            AudioStreams.setVolume(defaultMax, 1.4);
+            const floor = clampFixture();
+            AudioStreams.setVolume(floor, -0.5, 1.5);
+            const nonNumeric = clampFixture();
+            const nonNumericChanged = AudioStreams.setVolume(nonNumeric, "loud", 1.5);
+            return JSON.stringify({
+                overAmpChanged,
+                overAmp: overAmp.nodes.map(node => node.audio.volume),
+                overAmpMuted: overAmp.nodes.map(node => node.audio.muted),
+                ceiling: ceiling.nodes.map(node => node.audio.volume),
+                defaultMax: defaultMax.nodes.map(node => node.audio.volume),
+                floor: floor.nodes.map(node => node.audio.volume),
+                nonNumericChanged,
+                nonNumeric: nonNumeric.nodes.map(node => node.audio.volume)
+            });
+        }
+
        function serviceSummary(): string {
            const applications = AudioDevices.applications;
            return JSON.stringify({
@@ -57,7 +57,12 @@ Singleton {
        const coerced = PreferenceSchema.coerce(key, value);
        if (coerced === undefined)
            return false;
-        if (root.values[key] === coerced)
+        // A json value comes out of coerce() with a fresh identity every time,
+        // so `===` never held for one and an identical write still bumped the
+        // revision. The revision is what drives the video restore, the scheme
+        // reconciliation and the theme coalesce timer, so re-storing the same
+        // display map ran all three again for a change nobody made.
+        if (root.sameStoredValue(key, coerced))
            return true;

        // Reassign rather than mutate: QML does not notify on in-place changes
@@ -70,6 +75,19 @@ Singleton {
        return true;
    }

+    // Whether the store already holds `coerced` for `key`. Scalars compare by
+    // value; json compares by serialization, which is the only comparison an
+    // object or array has here. Two equal objects written in a different key
+    // order serialize differently and are treated as a change -- that is the
+    // old behaviour, so the comparison can only ever remove churn, never
+    // swallow a real write.
+    function sameStoredValue(key: string, coerced: var): bool {
+        const stored = root.values[key];
+        if (PreferenceSchema.spec(key)?.type === "json")
+            return stored !== undefined && JSON.stringify(stored) === JSON.stringify(coerced);
+        return stored === coerced;
+    }
+
    // Restores every schema default in one write. Complete by construction --
    // there is no hand-maintained list to fall out of sync with the schema.
    function resetDesktopDefaults(): void {
@@ -130,6 +148,14 @@ Singleton {
        printErrors: false
        atomicWrites: true

+        // Adopt writes made from outside the shell -- a hand edit, a script,
+        // a restored snapshot -- instead of holding a stale copy in memory
+        // and silently erasing them at the next save. A change made anywhere
+        // must survive everywhere; the shell is the editor, not the owner.
+        // The shell's own atomic writes land here too and reload as a no-op.
+        watchChanges: true
+        onFileChanged: this.reload()
+
        onLoaded: root.load()
        // No file yet is the normal first-run case, not an error.
        onLoadFailed: root.load()
@@ -145,7 +171,27 @@ Singleton {
    Timer {
        id: persistTimer
        interval: 0
-        onTriggered: preferencesFile.setText(JSON.stringify(root.values, null, 2) + "\n")
+        // Merge with what is on disk rather than overwriting it. This model
+        // was loaded at startup; a key written to the file since then -- a
+        // hand edit, a script, another shell instance during a session
+        // handoff -- would otherwise be erased by the next unrelated save,
+        // which is how a setting "changed itself back". Keys this shell has
+        // set win; keys it has never seen survive.
+        onTriggered: {
+            let disk = {};
+            try {
+                const text = preferencesFile.text();
+                if (text && text.trim().length > 0)
+                    disk = JSON.parse(text);
+            } catch (error) {
+                // An unreadable file loses the merge, never the write.
+            }
+            if (!disk || typeof disk !== "object")
+                disk = {};
+            const merged = Object.assign({}, disk, root.values);
+            root.values = merged;
+            preferencesFile.setText(JSON.stringify(merged, null, 2) + "\n");
+        }
    }

    // One-time move from the pre-Stage-1 location inside Quickshell's state
@@ -52,11 +52,74 @@ Singleton {

    readonly property var entries: [
        // ── Clock ───────────────────────────────────────────────────────────
+        // Group datetime, not clock: this drives the date menu, notification
+        // timestamps, and the lock screen — Date & Time owns it.
        {
-            key: "use24Hour", type: "bool", def: false, group: "clock",
+            key: "use24Hour", type: "bool", def: false, group: "datetime",
            label: "24-hour time",
            detail: "Use 18:30 instead of 6:30 PM"
        },
+        // ── Bar ─────────────────────────────────────────────────────────────
+        // The bar floats directly on the wallpaper; these keep it legible on
+        // grounds the theme never met, and choose which widgets earn a place.
+        {
+            key: "barTextTone", type: "enum", def: "theme", group: "bar",
+            label: "Bar text",
+            detail: "Follow the theme, or force a light or dark tone for the wallpaper you actually use",
+            options: [
+                { value: "theme", label: "Follow theme" },
+                { value: "light", label: "Light" },
+                { value: "dark", label: "Dark" }
+            ]
+        },
+        {
+            key: "barTextShadow", type: "bool", def: false, group: "bar",
+            label: "Bar text shadow",
+            detail: "A soft dark halo under every glyph and label in the bar"
+        },
+        {
+            key: "barBackdrop", type: "bool", def: false, group: "bar",
+            label: "Bar backdrop",
+            detail: "A subtle scrim fading down from the top edge"
+        },
+        {
+            key: "showWeatherWidget", type: "bool", def: true, group: "bar",
+            label: "Weather in the bar",
+            detail: "Beside the clock, once a forecast has been fetched"
+        },
+        {
+            key: "showMediaWidget", type: "bool", def: true, group: "bar",
+            label: "Media in the bar",
+            detail: "Now playing, click to pause"
+        },
+        {
+            key: "showClipboardButton", type: "bool", def: true, group: "bar",
+            label: "Clipboard button",
+            detail: "The history stays on Super+V either way"
+        },
+        {
+            key: "showCalendarCountdown", type: "bool", def: true, group: "bar",
+            label: "Calendar countdown",
+            detail: "Appears in the bar fifteen minutes before an event"
+        },
+
+        // ── Control Center ──────────────────────────────────────────────────
+        {
+            key: "ccShowFocus", type: "bool", def: true, group: "controlCenter",
+            label: "Focus in Control Center",
+            detail: "The session row at the top of the panel"
+        },
+        {
+            key: "ccShowHome", type: "bool", def: true, group: "controlCenter",
+            label: "Home in Control Center",
+            detail: "Your accessory shelf"
+        },
+        {
+            key: "ccShowPhone", type: "bool", def: true, group: "controlCenter",
+            label: "Phone in Control Center",
+            detail: "Vitals and reach-it actions"
+        },
+
        {
            key: "showSeconds", type: "bool", def: true, group: "clock",
            label: "Show seconds",
@@ -84,6 +147,121 @@ Singleton {
            label: "Graphics",
            detail: "Show graphics usage beside the workspace indicator"
        },
+        // Only ever visible on a machine that has a battery: the indicator
+        // gates on Battery.available as well as this, the way the graphics
+        // field gates on Vitals.gpuAvailable.
+        {
+            key: "showBattery", type: "bool", def: true, group: "vitals",
+            label: "Battery",
+            detail: "Show the charge level in the bar, on machines that have a battery"
+        },
+        // The number beside the icon, GNOME's "Show Battery Percentage".
+        // Off by default for the same reason GNOME ships it off: the icon
+        // already says what matters, and the number is for people who want it.
+        {
+            key: "showBatteryPercent", type: "bool", def: false, group: "vitals",
+            label: "Battery percentage",
+            detail: "Show the exact number beside the battery icon"
+        },
+
+        // Off by default: this is a coding-tool readout, not something a
+        // general-purpose desktop should show without being asked.
+        {
+            key: "showAgentUsage", type: "bool", def: false, group: "vitals",
+            label: "Agent usage",
+            detail: "Show how much of the busiest agent subscription has been used, beside the other vitals"
+        },
+
+        // ── Agents ──────────────────────────────────────────────────────────
+        // The escalation ladder and the usage collectors. `preferredAgent` is
+        // deliberately "none" out of the box: until an agent is chosen, crash
+        // notifications carry no action -- the desktop stays quiet rather than
+        // volunteering a tool the user never asked for.
+        {
+            key: "preferredAgent", type: "enum", def: "none", group: "agents",
+            label: "Preferred agent",
+            detail: "Who answers when the desktop offers to investigate something",
+            options: [
+                { value: "none", label: "None" },
+                { value: "claude", label: "Claude Code" },
+                { value: "codex", label: "Codex" }
+            ]
+        },
+        {
+            key: "crashDiagnoseOffer", type: "bool", def: true, group: "agents",
+            label: "Offer to diagnose crashes",
+            detail: "When a program dumps core, the notification carries a click that opens the preferred agent mid-investigation with the crash details in hand"
+        },
+        {
+            key: "reloadFailureOffer", type: "bool", def: true, group: "agents",
+            label: "Offer help when the shell fails to reload",
+            detail: "A broken change to the shell's own configuration offers the failing log to the agent"
+        },
+        {
+            key: "healthAgentHandoff", type: "bool", def: true, group: "agents",
+            label: "System Health hands off unrepairable checks",
+            detail: "A red check with no repair, or whose repair failed, grows an Ask-the-agent button carrying the check's snapshot"
+        },
+        {
+            key: "agentAutoApprove", type: "bool", def: true, group: "agents",
+            label: "Launched agents approve their own tools",
+            detail: "Investigations run without permission prompts. The diagnose skill still holds agents to reading rather than fixing, and root still goes through panama-sudo, reason and all"
+        },
+        {
+            key: "agentUsageClaude", type: "bool", def: true, group: "agents",
+            label: "Collect Claude Code usage",
+            detail: "Limits from Anthropic's usage endpoint, tokens from the local transcripts"
+        },
+        {
+            key: "agentUsageCodex", type: "bool", def: true, group: "agents",
+            label: "Collect Codex usage",
+            detail: "Limits over the Codex app-server, sessions from its local files"
+        },
+        {
+            key: "agentUsageRefreshMinutes", type: "int", def: 15, min: 5, max: 60, step: 5,
+            unit: " min", group: "agents",
+            label: "Refresh interval",
+            detail: "How often the usage collectors ask for fresh numbers, in minutes"
+        },
+
+        // ── Battery ─────────────────────────────────────────────────────────
+        // The two points at which the desktop starts telling you. Low is a
+        // quiet mention; critical is the one that interrupts, so it is
+        // published at a priority Do Not Disturb does not silence.
+        {
+            key: "batteryLowPercent", type: "int", def: 20, min: 5, max: 50, step: 5,
+            unit: "%", group: "battery",
+            label: "Warn at",
+            detail: "Mention the battery once it drops this low"
+        },
+        {
+            key: "batteryCriticalPercent", type: "int", def: 5, min: 1, max: 25, step: 1,
+            unit: "%", group: "battery",
+            label: "Urgent at",
+            detail: "Interrupt at this level, even during Do Not Disturb"
+        },
+        // What the desktop DOES at the critical threshold, beyond interrupting.
+        // Suspend by default, which is GNOME's behavior: sleep preserves the
+        // session at a level the firmware can hold for days, and the
+        // alternative -- a hard cut at 0% -- preserves nothing.
+        {
+            key: "batteryCriticalAction", type: "enum", def: "suspend", group: "battery",
+            label: "At the urgent level",
+            detail: "What happens when the battery reaches the urgent threshold while discharging",
+            options: [
+                { value: "suspend", label: "Suspend" },
+                { value: "nothing", label: "Only warn" }
+            ]
+        },
+
+        // Only offered where the firmware exposes a ceiling; the Power page
+        // hides the control entirely otherwise. 100 means charge to full.
+        {
+            key: "batteryChargeLimit", type: "int", def: 100, min: 50, max: 100, step: 5,
+            unit: "%", group: "battery",
+            label: "Stop charging at",
+            detail: "Charging to less than full is easier on the battery over years"
+        },

        // ── Dock ────────────────────────────────────────────────────────────
        {
@@ -168,6 +346,9 @@ Singleton {
                }
            ]
        },
+        // Set by the duration chips on the Focus tab, which is also where
+        // focusModes renders and where the focus group routes -- one editor,
+        // one page, so search and the docs point at the only place it exists.
        {
            key: "focusDurationMinutes", type: "int", def: 45, min: 5, max: 180, step: 5,
            unit: "min",
@@ -628,6 +809,88 @@ Singleton {
            detail: "Paste the primary selection in GTK and native Wayland applications",
            hypr: { path: ["misc", "middle_click_paste"], option: "misc:middle_click_paste", readAs: "bool" }
        },
+        {
+            key: "focusOnClose", type: "enum", def: 0, group: "pointer",
+            label: "Focus after closing",
+            detail: "Which window takes keyboard focus when the focused one goes away",
+            // Designed as a two-way choice; the compositor publishes three.
+            //   map: [{"mru":2},{"cursor":1},{"next":0}]
+            // and 0 -- the value this desktop runs on today -- is "next in the
+            // stack", which is neither of the two the design named. Hiding it
+            // would make the shipped default unreachable from its own dropdown,
+            // and enum-hypr-map-contract refuses an enum that drops a published
+            // value for exactly that reason.
+            options: [
+                { value: 0, label: "Next in the stack",
+                  detail: "Whichever window Hyprland has next in the layout order" },
+                { value: 1, label: "Under the pointer",
+                  detail: "Whatever window the pointer happens to be over" },
+                { value: 2, label: "Most recently used",
+                  detail: "The window you were on before this one" }
+            ],
+            hypr: { path: ["input", "focus_on_close"], option: "input:focus_on_close", readAs: "int" }
+        },
+        {
+            key: "scrollMethod", type: "enum", def: "", group: "pointer",
+            label: "Scroll method",
+            detail: "How a pointing device turns movement into scrolling",
+            // No `map` is published for this one -- it is a plain string option,
+            // and the words it accepts live in its description instead:
+            // [2fg/edge/on_button_down/no_scroll].
+            //
+            // Unset is a real state rather than an absence, and it is the state
+            // Panama ships: getoption answers "[[EMPTY]]" until something writes
+            // the option, and an empty value means "whatever libinput picks for
+            // this device", which is the branch every stock Hyprland takes. So
+            // empty is offered as a choice of its own -- without it the setting
+            // would be a one-way door, and its default would be unreachable.
+            // Writing "" reads back as "" with set:true, the same round trip
+            // input:kb_variant has made for as long as it has been empty.
+            options: [
+                { value: "", label: "Whatever suits the device",
+                  detail: "Two fingers on a touchpad, the wheel on a mouse" },
+                { value: "2fg", label: "Two fingers" },
+                { value: "edge", label: "Along the edge of the touchpad" },
+                { value: "on_button_down", label: "While a button is held" },
+                { value: "no_scroll", label: "Never scroll" }
+            ],
+            hypr: { path: ["input", "scroll_method"], option: "input:scroll_method", readAs: "str" }
+        },
+        {
+            key: "scrollButton", type: "int", def: 0, min: 0, max: 300, step: 1,
+            group: "pointer",
+            label: "Scroll button",
+            detail: "Which button is held to scroll, as an evdev code; 0 lets the device choose",
+            // The range is the compositor's own rather than a guess: descriptions
+            // gives min 0, max 300. Only meaningful while Scroll method is
+            // "While a button is held", which is a UI condition, not a schema one
+            // -- the value stays valid and stored either way.
+            hypr: { path: ["input", "scroll_button"], option: "input:scroll_button", readAs: "int" }
+        },
+        {
+            key: "cursorHideWhileTyping", type: "bool", def: false, group: "pointer",
+            label: "Hide pointer while typing",
+            detail: "The pointer vanishes on the next keystroke and returns when you move it",
+            // A `cursor:` option rather than an `input:` one, so its read-back in
+            // the Lua sits in a cursor table of its own; see hypr/input.lua.
+            hypr: { path: ["cursor", "hide_on_key_press"], option: "cursor:hide_on_key_press", readAs: "bool" }
+        },
+        {
+            key: "cursorWarpOnWorkspaceChange", type: "bool", def: false, group: "pointer",
+            label: "Jump pointer to the focused display",
+            detail: "Moves the pointer to the last focused window after switching workspace",
+            // A switch here, an integer in the compositor -- the same shape
+            // autoHdr has, and `readAs: "int"` is what keeps the two sides in
+            // agreement. The published map is
+            //   map: [{"force":2},{"enable":1},{"disable":0}]
+            // and "force" -- warp even when the pointer is already on that
+            // display -- is deliberately not offered: a third state would turn a
+            // switch into a dropdown for a distinction almost nobody wants.
+            // enum-hypr-map-contract governs enums only, so this is a decision
+            // rather than a violation, but it IS a decision: value 2 is not
+            // reachable from Settings.
+            hypr: { path: ["cursor", "warp_on_change_workspace"], option: "cursor:warp_on_change_workspace", readAs: "int" }
+        },

        // ── Touchpad ────────────────────────────────────────────────────────
        //
@@ -685,6 +948,28 @@ Singleton {
            detail: "Pressing left and right together acts as a middle click",
            hypr: { path: ["input", "touchpad", "middle_button_emulation"], option: "input:touchpad:middle_button_emulation", readAs: "bool" }
        },
+        {
+            key: "touchpadClickfinger", type: "bool", def: false, group: "touchpad",
+            label: "Two-finger right-click",
+            detail: "One, two, or three fingers pressing down give left, right, and middle click, instead of clicking by which part of the pad you press",
+            hypr: { path: ["input", "touchpad", "clickfinger_behavior"], option: "input:touchpad:clickfinger_behavior", readAs: "bool" }
+        },
+        {
+            key: "touchpadTapAndDrag", type: "bool", def: true, group: "touchpad",
+            label: "Tap and drag",
+            detail: "A tap followed straight away by a tap-and-hold starts a drag, with nothing pressed down",
+            // Hyphens in the option name, underscores in the Lua path -- the same
+            // split tap-to-click documents above, and the only other option in
+            // the touchpad section spelled that way.
+            //
+            // `hyprctl descriptions` contradicts itself here: it reports current
+            // false while `hyprctl getoption` answers bool true with set:false,
+            // meaning nothing has ever written it and it is sitting on
+            // Hyprland's own default of true. getoption is the authority, since
+            // it is what the write path verifies against, so true is what ships
+            // and nothing changes on a machine that has a touchpad.
+            hypr: { path: ["input", "touchpad", "tap_and_drag"], option: "input:touchpad:tap-and-drag", readAs: "bool" }
+        },

        // Tuning for the three-finger gestures registered in hypr/input.lua.
        // The gestures themselves are not settings: Hyprland reads a gesture
@@ -748,31 +1033,31 @@ Singleton {
            hypr: { path: ["general", "snap", "enabled"], option: "general:snap:enabled", readAs: "bool" }
        },
        {
-            key: "workspaceBackAndForth", type: "bool", def: false, group: "multitasking",
+            key: "workspaceBackAndForth", type: "bool", def: false, group: "workspaces",
            label: "Switch back and forth",
            detail: "Selecting the workspace you are already on returns you to the previous one",
            hypr: { path: ["binds", "workspace_back_and_forth"], option: "binds:workspace_back_and_forth", readAs: "bool" }
        },
        {
-            key: "allowWorkspaceCycles", type: "bool", def: false, group: "multitasking",
+            key: "allowWorkspaceCycles", type: "bool", def: false, group: "workspaces",
            label: "Wrap around at the ends",
            detail: "Moving past the last workspace continues from the first",
            hypr: { path: ["binds", "allow_workspace_cycles"], option: "binds:allow_workspace_cycles", readAs: "bool" }
        },
        {
-            key: "focusOnActivate", type: "bool", def: false, group: "multitasking",
+            key: "focusOnActivate", type: "bool", def: false, group: "workspaces",
            label: "Let applications take focus",
            detail: "An application asking for attention is switched to, rather than only highlighted",
            hypr: { path: ["misc", "focus_on_activate"], option: "misc:focus_on_activate", readAs: "bool" }
        },
        {
-            key: "windowSwallow", type: "bool", def: false, group: "multitasking",
+            key: "windowSwallow", type: "bool", def: false, group: "workspaces",
            label: "Hide the terminal that launched a window",
            detail: "A terminal disappears while an application started from it is open, and returns when it closes",
            hypr: { path: ["misc", "enable_swallow"], option: "misc:enable_swallow", readAs: "bool" }
        },
        {
-            key: "mouseMoveFocusesMonitor", type: "bool", def: true, group: "multitasking",
+            key: "mouseMoveFocusesMonitor", type: "bool", def: true, group: "workspaces",
            label: "Pointer changes active display",
            detail: "Moving the pointer to another display makes it the active one",
            hypr: { path: ["misc", "mouse_move_focuses_monitor"], option: "misc:mouse_move_focuses_monitor", readAs: "bool" }
@@ -789,9 +1074,14 @@ Singleton {
        // this app refuses to ship.
        {
            key: "magnifierFactor", type: "real", def: 1.0, min: 1.0, max: 5.0, step: 0.1,
-            group: "accessibility",
+            unit: "×", group: "accessibility",
            label: "Magnifier",
-            detail: "Magnifies the screen around the pointer. 1.0 is off",
+            // The readout is "1.00 ×", so the detail says "1.00 ×" too. It used
+            // to say "1.0 is off" beside a slider reading 1.00, and the page
+            // carried a `zeroLabel: "Off"` that could never fire: the minimum
+            // IS 1.0, so the value is never 0 and the zero label was dead copy.
+            // Off is a magnification of one, and that is what both lines say.
+            detail: "Magnifies the screen around the pointer. 1.00 × is off",
            hypr: { path: ["cursor", "zoom_factor"], option: "cursor:zoom_factor", readAs: "float" }
        },
        {
@@ -821,6 +1111,33 @@ Singleton {
            detail: "How much darker unfocused windows are",
            hypr: { path: ["decoration", "dim_strength"], option: "decoration:dim_strength", readAs: "float" }
        },
+        {
+            key: "colorFilter", type: "enum", def: "none", group: "accessibility",
+            label: "Color filter",
+            detail: "A whole-screen filter rendered by the compositor — grayscale, or a correction for one kind of color blindness. Costs nothing when off.",
+            // No hypr mapping, deliberately: hyprctl stores decoration:screen_shader
+            // as a shader *path*, not this enum, so a hypr: block would fail the
+            // shape and sweep contracts on read-back. hypr/looks.lua maps the enum
+            // to a shipped shader for reloads; SystemSettings.applyColorFilter does
+            // the same mapping live.
+            options: [
+                { value: "none", label: "None" },
+                { value: "grayscale", label: "Grayscale" },
+                { value: "protanopia", label: "Protanopia" },
+                { value: "deuteranopia", label: "Deuteranopia" },
+                { value: "tritanopia", label: "Tritanopia" }
+            ]
+        },
+        {
+            key: "visualAlerts", type: "bool", def: false, group: "accessibility",
+            label: "Flash the screen for notifications",
+            // No hypr mapping and no gsettings mapping: the flash is drawn by
+            // modules/notifications/VisualBell.qml, one per screen, and fires
+            // on the same notifications the bell would ring for -- except that
+            // it is deliberately NOT gated on the event-sounds switch, since a
+            // visual alert exists for people who cannot hear the bell.
+            detail: "A single flash at the edges of every screen when a notification arrives that would ring the bell"
+        },

        // ── Gaming ──────────────────────────────────────────────────────────
        // What Panama does while a game runs. gamemode tells us when that
@@ -908,6 +1225,29 @@ Singleton {
            key: "wallpaperPerMonitor", type: "json", def: ({}), group: "wallpaper", internal: true,
            label: "Per-display backgrounds", detail: "Background assigned to each connected display"
        },
+        // Video wallpapers play through mpvpaper (services/VideoWallpaper.qml);
+        // the active video rides wallpaperPath like any still, routed by
+        // extension. These two only shape discovery and the battery policy.
+        {
+            key: "videoWallpaperDir", type: "string", def: "Videos/Wallpapers", group: "wallpaper",
+            pattern: "^~?/?[A-Za-z0-9 ._/+@'-]{1,160}$",
+            label: "Video wallpaper folder",
+            detail: "Where the picker looks for videos. Relative to your home folder unless it starts with /"
+        },
+        // Its own key, not wallpaperPath: the still pipeline persists its
+        // policy transactionally and once clobbered a stored video path.
+        // Two owners, two keys.
+        {
+            key: "videoWallpaperPath", type: "string", def: "", group: "wallpaper", internal: true,
+            pattern: "^(|/[^,\n]+)$",
+            label: "Video wallpaper",
+            detail: "The video playing as the desktop background"
+        },
+        {
+            key: "videoWallpaperPauseOnBattery", type: "bool", def: true, group: "wallpaper",
+            label: "Pause video wallpaper on battery",
+            detail: "Freezes on the current frame and resumes on wall power"
+        },

        // ── Lock-screen appearance ─────────────────────────────────────────
        // scripts/panama-lock validates these again before generating a state
@@ -970,6 +1310,54 @@ Singleton {
            detail: "Requires your password when the machine wakes"
        },

+        // The same three timings again, for when the machine is running on
+        // its own battery. hypridle has no concept of a power source, so
+        // there is one generated config and panama-idle rebuilds it from
+        // whichever set applies when the charger comes or goes.
+        //
+        // Shorter defaults, because the cost of an idle screen differs: on
+        // wall power it is a screen, on battery it is the rest of your
+        // afternoon. A machine with no battery never reads these at all.
+        {
+            key: "screenBlankMinutesBattery", type: "int", def: 2, min: 0, max: 120, step: 1,
+            unit: "min", group: "idleBattery",
+            label: "Turn the screen off after",
+            detail: "On battery. Blanks the display; nothing is locked yet"
+        },
+        {
+            key: "lockMinutesBattery", type: "int", def: 5, min: 0, max: 240, step: 1,
+            unit: "min", group: "idleBattery",
+            label: "Lock after",
+            detail: "On battery. Requires your password to get back in"
+        },
+        {
+            key: "suspendMinutesBattery", type: "int", def: 20, min: 0, max: 480, step: 5,
+            unit: "min", group: "idleBattery",
+            label: "Suspend after",
+            detail: "On battery, sleeping is what makes the charge last"
+        },
+
+        // ── Power button ────────────────────────────────────────────────────
+        // logind is told to ignore the power key -- config/copy ships the
+        // drop-in -- so what a press does is the compositor's decision rather
+        // than the system's, and changing it needs no root.
+        //
+        // No `hypr` block: this is not a compositor option, it is read by
+        // config/dot/hypr/keybinds.lua the way the workspace rules are. The
+        // bind evaluates it AT PRESS TIME rather than at config time, so a
+        // change here applies to the very next press and no reload is needed.
+        {
+            key: "powerButtonAction", type: "enum", def: "menu", group: "power",
+            label: "Pressing the power button",
+            detail: "The system ignores the key; Panama decides — so a bumped button never yanks the plug",
+            options: [
+                { value: "menu", label: "Shows the power menu" },
+                { value: "suspend", label: "Suspends" },
+                { value: "poweroff", label: "Powers off (two-press)" },
+                { value: "nothing", label: "Does nothing" }
+            ]
+        },
+
        // ── Night light schedule ────────────────────────────────────────────
        // Hours as decimals, so 17.5 is half past five. Wrapping past midnight
        // is normal here and is what the shipped values do: on at 17:00, off at
@@ -1039,6 +1427,22 @@ Singleton {
            detail: "Named custom colour schemes and accent pairs",
            internal: true
        },
+        // The remembered theme per scheme: flipping light/dark lands on the
+        // theme you last chose for that side, never a forced default.
+        {
+            key: "themeDark", type: "string", def: "moon", group: "appearance",
+            pattern: "^[a-z0-9][a-z0-9-]{0,63}$",
+            label: "Dark theme",
+            detail: "The theme applied while the desktop is dark",
+            internal: true
+        },
+        {
+            key: "themeLight", type: "string", def: "day", group: "appearance",
+            pattern: "^[a-z0-9][a-z0-9-]{0,63}$",
+            label: "Light theme",
+            detail: "The theme applied while the desktop is light",
+            internal: true
+        },

        // ── Application themes ─────────────────────────────────────────────
        // ColorScheme owns GTK's light/dark theme. These are the two theme
@@ -1158,20 +1562,18 @@ Singleton {
                { value: "right", label: "Right" }
            ]
        },
+        // Panama's own windows (Settings) draw their own titlebar and follow
+        // the same rules as GNOME apps. Off is pure Hyprland: Super+Q closes,
+        // Super+drag moves, Escape still works.
        {
-            key: "titlebarMaximizeButton", type: "bool", def: false, group: "titlebar",
-            label: "Maximize button",
-            detail: "Show a maximize button in application titlebars that support it"
-        },
-        {
-            key: "titlebarDoubleClick", type: "enum", def: "toggle-maximize", group: "titlebar",
-            label: "Double-click titlebar",
-            detail: "Choose what a double-click on an application titlebar does",
-            options: [
-                { value: "toggle-maximize", label: "Toggle maximize" },
-                { value: "none", label: "Do nothing" }
-            ]
+            key: "panamaTitlebar", type: "bool", def: true, group: "titlebar",
+            label: "Titlebar on Panama windows",
+            detail: "Hide it and the window is pure Hyprland — Super+Q closes, Super+drag moves"
        },
+        // titlebarMaximizeButton and titlebarDoubleClick used to live here.
+        // Removed on purpose: Hyprland has no minimize, maximize is noise in a
+        // tiler, and DesktopStyle now pushes a close-only button-layout and
+        // leaves GNOME's double-click default alone.

        // ── Accessibility ───────────────────────────────────────────────────
        // Backed by gsettings so GTK applications agree with the shell, and
@@ -1221,28 +1623,44 @@ Singleton {
            detail: "Which GPU the graphics readout in the bar measures"
        },

+        // ── Search ──────────────────────────────────────────────────────────
+        // The launcher's web search appends the query to this. It shipped
+        // pointing at the author's personal bang redirector once; a stranger's
+        // searches belong to no one's server but the engine they chose.
+        {
+            key: "webSearchUrl", type: "string",
+            def: "https://duckduckgo.com/?q=", group: "search",
+            pattern: "^https://[^\\s]{1,200}$",
+            label: "Web search engine",
+            detail: "Where the launcher's web search sends a query; the search text is appended"
+        },
+
        // ── Weather location ────────────────────────────────────────────────
        // Coordinates rather than a place name, because that is what Open-Meteo
        // takes and it needs no API key. weatherLocation is only the label shown
        // in the UI; it is never sent anywhere, so it can say whatever makes the
        // reading recognizable.
        {
-            key: "weatherLatitude", type: "real", def: 27.7375, min: -90, max: 90, step: 0.0001,
+            key: "weatherLatitude", type: "real", def: 0, min: -90, max: 90, step: 0.0001,
            group: "weather", internal: true,
            label: "Latitude",
            detail: "Set by choosing a location"
        },
        {
-            key: "weatherLongitude", type: "real", def: -82.6861, min: -180, max: 180, step: 0.0001,
+            key: "weatherLongitude", type: "real", def: 0, min: -180, max: 180, step: 0.0001,
            group: "weather", internal: true,
            label: "Longitude",
            detail: "Set by choosing a location"
        },
+        // Empty until a location is chosen. The shipped value was once the
+        // author's home town, which confidently reported his weather on every
+        // machine anywhere; an unset location fetches nothing and says so
+        // instead.
        {
-            key: "weatherLocation", type: "string", def: "Local weather", group: "weather",
+            key: "weatherLocation", type: "string", def: "", group: "weather",
            internal: true,
            // Display only -- never sent to the weather service.
-            pattern: "^[^\\n]{1,64}$",
+            pattern: "^[^\\n]{0,64}$",
            label: "Weather location",
            detail: "The place the weather reading is for"
        },
@@ -1280,6 +1698,38 @@ Singleton {
            label: "Visible banners",
            detail: "Maximum notification banners shown at once"
        },
+        // The one hole anyone is allowed to punch in Do Not Disturb. Off by
+        // default, because Do Not Disturb that lets something through anyway is
+        // not the thing most people asked for -- and "critical" is the sender's
+        // word, not yours, so an application that calls everything critical
+        // would otherwise defeat the switch on its own say-so. Turned on, it
+        // shows a banner for critical notifications while a mode or a manual Do
+        // Not Disturb is silencing everything else; the per-application urgency
+        // override is how you decide which senders get to claim it.
+        {
+            key: "criticalBreaksThrough", type: "bool", def: false,
+            group: "notifications",
+            label: "Critical alerts break through",
+            detail: "Show critical notifications as banners even while Do Not Disturb is on"
+        },
+
+        // ── Sound ───────────────────────────────────────────────────────────
+        // The two audio preferences that are Panama's own. Everything else on
+        // the Sound page is live PipeWire or a GNOME desktop key, and belongs
+        // to the system rather than to this file.
+        //
+        // Both are read by scripts/panama-osd as well as by the shell, so the
+        // volume keys behave the same whether the panel is open or not.
+        {
+            key: "overAmplification", type: "bool", def: false, group: "sound",
+            label: "Over-amplification",
+            detail: "Lets the volume slider go to 150% — louder, at the cost of distortion on some hardware"
+        },
+        {
+            key: "volumeChangeBlip", type: "bool", def: true, group: "sound",
+            label: "Volume-change blip",
+            detail: "A short click each time the volume keys move the output level"
+        },

        // ── Capture ─────────────────────────────────────────────────────────
        // Directories and encoder arguments are enums rather than free text:
@@ -1303,14 +1753,34 @@ Singleton {
            label: "Recording folder",
            detail: "Where screen recordings are saved. Relative to your home folder unless it starts with /"
        },
+        // What a recording hears. Off by default, which is GNOME's default
+        // too -- a screencast that silently captured the microphone would be
+        // a privacy incident, not a feature. The @DEFAULT_*@ tokens are
+        // PulseAudio's own always-current aliases, so the recording follows
+        // the device Sound settings has selected rather than naming one.
        {
-            key: "recorderArgs", type: "enum", def: "-c h264_vaapi -d /dev/dri/renderD128",
+            key: "recorderAudio", type: "enum", def: "none", group: "capture",
+            label: "Recording audio",
+            detail: "What screen recordings capture alongside the video",
+            options: [
+                { value: "none", label: "No audio" },
+                { value: "system", label: "System audio" },
+                { value: "microphone", label: "Microphone" }
+            ]
+        },
+
+        // "auto" stands in for the render node until record time:
+        // /dev/dri/renderD128 was baked into every option once, which is one
+        // machine's enumeration and frequently the wrong node on hybrid
+        // graphics. Capture.qml resolves it when recording starts.
+        {
+            key: "recorderArgs", type: "enum", def: "-c h264_vaapi -d auto",
            group: "capture",
            label: "Recording encoder",
            detail: "Hardware encoding keeps recording off the processor while gaming",
            options: [
-                { value: "-c h264_vaapi -d /dev/dri/renderD128", label: "VAAPI H.264" },
-                { value: "-c hevc_vaapi -d /dev/dri/renderD128", label: "VAAPI HEVC" },
+                { value: "-c h264_vaapi -d auto", label: "VAAPI H.264" },
+                { value: "-c hevc_vaapi -d auto", label: "VAAPI HEVC" },
                { value: "-c libx264", label: "CPU x264" }
            ]
        },
@@ -1347,7 +1817,7 @@ Singleton {
        // each chord and falls back to the shipped one, so a hand-edited file
        // cannot cost you a keymap.
        //
-        // Edited through the Input & Shortcuts page rather than as a row, hence
+        // Edited through the Keyboard page (under Input) rather than as a row, hence
        // internal.
        {
            key: "keybindOverrides", type: "json", def: ({}), group: "input",
@@ -1356,21 +1826,88 @@ Singleton {
            detail: "Shortcuts you have moved from their shipped chord"
        },

+        // ── Custom shortcuts ────────────────────────────────────────────────
+        // [ { chord, kind, target, label } ]. Data, never code: `kind` is one of
+        // app | shell | window, `target` is a validated id resolved through the
+        // whitelist tables in hypr/actions.lua, and an entry that fails any check
+        // is silently not emitted. This is what keeps a user-editable file from
+        // being executable even though it now describes shortcuts the user
+        // invented. Edited through the Keyboard page, hence internal.
+        {
+            key: "customBinds", type: "json", def: [], group: "input",
+            internal: true,
+            label: "Custom shortcuts",
+            detail: "Shortcuts you invented: each one launches an application, triggers a shell action, or moves a window"
+        },
+
+        // ── Per-application window rules ────────────────────────────────────
+        // [ { class, label, float, center, size, workspace, noAnim, game,
+        // noDim, pin } ]. `class` is matched literally (hypr/rules.lua escapes
+        // it before Hyprland's RE2 sees it); `size` is [w, h] or null;
+        // `workspace` is 1..10 or null; everything else is a boolean. Rules
+        // matching the shell's own surfaces are refused at both ends. Edited
+        // through the Windows page, hence internal.
+        {
+            key: "windowRules", type: "json", def: [], group: "multitasking",
+            internal: true,
+            label: "Application window rules",
+            detail: "How specific applications behave when they open: floating, size, workspace, animations"
+        },
+
+        // ── Four-finger gestures ────────────────────────────────────────────
+        // Each holds {} (unassigned) or a named action { kind, target, label },
+        // the same shape customBinds stores and the same whitelists resolve.
+        // Registered at compositor config time, so assigning one reloads.
+        {
+            key: "gestureFourUp", type: "json", def: ({}), group: "touchpad",
+            internal: true,
+            label: "Four-finger swipe up",
+            detail: "What a four-finger upward swipe does"
+        },
+        {
+            key: "gestureFourDown", type: "json", def: ({}), group: "touchpad",
+            internal: true,
+            label: "Four-finger swipe down",
+            detail: "What a four-finger downward swipe does"
+        },
+        {
+            key: "gestureFourLeft", type: "json", def: ({}), group: "touchpad",
+            internal: true,
+            label: "Four-finger swipe left",
+            detail: "What a four-finger leftward swipe does"
+        },
+        {
+            key: "gestureFourRight", type: "json", def: ({}), group: "touchpad",
+            internal: true,
+            label: "Four-finger swipe right",
+            detail: "What a four-finger rightward swipe does"
+        },
+
        // ── Display configuration ───────────────────────────────────────────
-        // { "<output>": { mode, scale, transform, x, y, primary } }, applied by
-        // hypr/monitors.lua on top of the shipped values. Color management and
-        // bit depth are deliberately not here: those carry a documented
-        // screencopy tradeoff that a settings page cannot explain at the moment
-        // you would be changing it.
+        // { "<output>": { mode, scale, transform, x, y, primary, vrrMode,
+        // colorProfile, bitdepth, sdrBrightness, sdrSaturation, mirrorOf } },
+        // applied by hypr/monitors.lua on top of the shipped values. Everything
+        // past `primary` is optional, so records written before those fields
+        // existed still load and the shipped defaults stand for them.
        {
            key: "displays", type: "json", def: ({}), group: "display",
            internal: true,
            label: "Display configuration",
-            detail: "Resolution, scale, rotation, position, and primary display"
+            detail: "Resolution, scale, rotation, position, primary display, color, VRR override, and mirroring"
        },

        // ── Per-application notification rules ──────────────────────────────
-        // { "<appId>": { enabled, showOnLockScreen, showContentOnLockScreen } }
+        // { "<appId>": { enabled, sound, display, urgency, lastSeenMs, name,
+        // icon } -- every field past `enabled` is optional, so rules written
+        // when this held only `enabled` still load. Lock-screen fields from
+        // older rules are dropped at normalization; hyprlock cannot render
+        // notifications.
+        //
+        // `name` and `icon` are a cache for the settings list, not the source:
+        // resolution stays live-first through DesktopEntries, and these only
+        // stand in for an application that is not installed (or not scanned
+        // yet). `lastSeenMs` is stamped on every notification and is what puts
+        // an application in the "Recent" section.
        //
        // Absent means "no rule", which is not the same as a rule that allows
        // everything: a new application must be able to notify without needing
@@ -1381,10 +1918,16 @@ Singleton {
            key: "notificationAppRules", type: "json", def: ({}), group: "notifications",
            internal: true,
            label: "Application notification rules",
-            detail: "Per-application notification and lock-screen visibility preferences"
+            detail: "Per-application notification sound, banner, and urgency preferences"
        },

        // ── Internal ────────────────────────────────────────────────────────
+        {
+            key: "welcomeSeen", type: "bool", def: false, group: "internal",
+            internal: true,
+            label: "Welcome shown",
+            detail: "Set once the first-run welcome has been dismissed. Restoring defaults shows it again, which is intended: a reset machine is one somebody wants introduced to them"
+        },
        {
            key: "lastPage", type: "string", def: "home", group: "internal",
            internal: true,
@@ -19,6 +19,26 @@ Singleton {
    readonly property bool showSeconds: DesktopPreferences.get("showSeconds")
    readonly property bool showWeekday: DesktopPreferences.get("showWeekday")

+    // ── Bar ─────────────────────────────────────────────────────────────────
+    // Legibility first: the bar sits on the wallpaper, so it may need a tone,
+    // a shadow or a scrim the theme cannot know about. `barTextTone` itself is
+    // read by Theme, which turns it into the barFg family the widgets bind to.
+    readonly property bool barTextShadow: DesktopPreferences.get("barTextShadow")
+    readonly property bool barBackdrop: DesktopPreferences.get("barBackdrop")
+
+    // Which widgets earn a place. Each is ANDed with the widget's own state
+    // condition, so turning one on never conjures a pill with nothing in it.
+    readonly property bool showWeatherWidget: DesktopPreferences.get("showWeatherWidget")
+    readonly property bool showMediaWidget: DesktopPreferences.get("showMediaWidget")
+    readonly property bool showClipboardButton: DesktopPreferences.get("showClipboardButton")
+    readonly property bool showCalendarCountdown: DesktopPreferences.get("showCalendarCountdown")
+
+    // ── Control Center ──────────────────────────────────────────────────────
+    // One bool per section of the quick settings panel that is worth hiding.
+    readonly property bool ccShowFocus: DesktopPreferences.get("ccShowFocus")
+    readonly property bool ccShowHome: DesktopPreferences.get("ccShowHome")
+    readonly property bool ccShowPhone: DesktopPreferences.get("ccShowPhone")
+
    // ── Weather ─────────────────────────────────────────────────────────────
    // Coordinates taken from the GNOME night-light setting, which had already
    // resolved the location. Uses Open-Meteo, which needs no API key.
@@ -38,6 +58,26 @@ Singleton {
    readonly property bool showCpu: DesktopPreferences.get("showCpu")
    readonly property bool showMemory: DesktopPreferences.get("showMemory")
    readonly property bool showGpu: DesktopPreferences.get("showGpu")
+    readonly property bool showBattery: DesktopPreferences.get("showBattery")
+    readonly property bool showBatteryPercent: DesktopPreferences.get("showBatteryPercent")
+    readonly property bool showAgentUsage: DesktopPreferences.get("showAgentUsage")
+
+    // ── Agents ──────────────────────────────────────────────────────────────
+    // Who the desktop hands a failure to, what it is allowed to hand over, and
+    // which usage collectors run. `showAgentUsage` stays with the vitals above:
+    // it is the bar's switch, and the Agents page mirrors it.
+    readonly property string preferredAgent: DesktopPreferences.get("preferredAgent")
+    readonly property bool crashDiagnoseOffer: DesktopPreferences.get("crashDiagnoseOffer")
+    readonly property bool reloadFailureOffer: DesktopPreferences.get("reloadFailureOffer")
+    readonly property bool healthAgentHandoff: DesktopPreferences.get("healthAgentHandoff")
+    readonly property bool agentAutoApprove: DesktopPreferences.get("agentAutoApprove")
+    readonly property bool agentUsageClaude: DesktopPreferences.get("agentUsageClaude")
+    readonly property bool agentUsageCodex: DesktopPreferences.get("agentUsageCodex")
+    readonly property int agentUsageRefreshMinutes: DesktopPreferences.get("agentUsageRefreshMinutes")
+
+    // ── Battery ─────────────────────────────────────────────────────────────
+    readonly property int batteryLowPercent: DesktopPreferences.get("batteryLowPercent")
+    readonly property int batteryCriticalPercent: DesktopPreferences.get("batteryCriticalPercent")

    // amdgpu exposes utilisation here. Verified present on this machine; the
    // widget hides itself if the path is missing rather than showing zeros.
@@ -55,6 +95,28 @@ Singleton {
    readonly property int notificationTimeoutCriticalMs: DesktopPreferences.get("notificationTimeoutCriticalMs") // 0 = never auto-expire
    readonly property int notificationHistoryLimit: DesktopPreferences.get("notificationHistoryLimit")
    readonly property int maxVisibleToasts: DesktopPreferences.get("maxVisibleToasts")
+    // The single exception to Do Not Disturb, read by the popup gate in
+    // services/Notifs.qml. Off means Do Not Disturb is absolute.
+    readonly property bool criticalBreaksThrough: DesktopPreferences.get("criticalBreaksThrough")
+
+    // ── Accessibility ───────────────────────────────────────────────────────
+    // Reduce motion. Theme.qml turns this into the dur* tokens, so every
+    // Behavior and NumberAnimation in the shell obeys it without knowing it
+    // exists. Read through here rather than from the store directly because
+    // Theme reads it on every animated property in the shell.
+    readonly property bool animationsEnabled: DesktopPreferences.get("animationsEnabled")
+
+    // Read on every notification that would ring the bell, by the per-screen
+    // VisualBell overlay. Lives here rather than being read from the store
+    // directly, like every other value the shell consults at speed.
+    readonly property bool visualAlerts: DesktopPreferences.get("visualAlerts")
+
+    // ── Sound ───────────────────────────────────────────────────────────────
+    // Over-amplification is the clamp ceiling for output volume: off means 1.0,
+    // on means 1.5. Every slider and the volume keys read the same switch, so
+    // the ceiling cannot differ depending on where you changed the volume from.
+    readonly property bool overAmplification: DesktopPreferences.get("overAmplification")
+    readonly property bool volumeChangeBlip: DesktopPreferences.get("volumeChangeBlip")

    // ── Focus ──────────────────────────────────────────────────────────────
    // One deliberate default rather than a preset picker: quick settings and
@@ -89,4 +151,5 @@ Singleton {
    // Passed to wf-recorder. Uses VAAPI on the AMD card so recording does not
    // cost CPU while gaming.
    readonly property string recorderArgs: DesktopPreferences.get("recorderArgs")
+    readonly property string recorderAudio: DesktopPreferences.get("recorderAudio")
 }
@@ -20,28 +20,68 @@ Singleton {
    id: root

    // ── Color scheme ───────────────────────────────────────────────────────
-    // Tokyo Night ships an official light variant (Day), so light mode is that
-    // rather than a palette invented to merely not be dark. The two share the
-    // same hues at different lightness, which is what lets the Prism identity
-    // survive the switch: blue still leads into orchid, it is simply a darker
-    // blue on a lighter ground.
+    // The scheme still exists as a boolean because alphas and a handful of
+    // mix directions depend on which side of the ground the theme sits — but
+    // the palette itself now comes from the active theme record.
    //
-    // Every token below is a binding on this, so flipping it repaints the whole
+    // Every token below is a binding, so selecting a theme repaints the whole
    // shell without anything needing to know it happened.
    readonly property bool dark: DesktopPreferences.get("colorScheme") !== "light"

    // ── Palette ─────────────────────────────────────────────────────────────
-    // Canonical Tokyo Night Moon. `accent` matches the GNOME accent exactly.
-    readonly property color bg: root.dark ? "#222436" : "#e1e2e7"
-    readonly property color bgDark: root.dark ? "#1e2030" : "#d3d5de"
-    readonly property color bgHighlight: root.dark ? "#2f334d" : "#c4c8da"
-    readonly property color bgPanel: root.dark ? "#2e2f3d" : "#d9dae3" // dock glass surface
-    readonly property color bgPopover: root.dark ? "#21212f" : "#eaeaee" // Openbar submenu background
+    // The active theme's palette — ThemeProfiles resolves it and it is always
+    // complete: a shipped theme carries its own, a custom theme without one
+    // inherits its scheme's default (Tokyo Moon or Tokyo Day) from the
+    // catalog. Nothing here needs a per-token fallback.
+    readonly property var palette: ThemeProfiles.activePalette

-    readonly property color fg: root.dark ? "#c8d3f5" : "#3760bf"
-    readonly property color fgDim: root.dark ? "#828bb8" : "#6172b0"
-    readonly property color fgMuted: root.dark ? "#636da6" : "#848cb5"
-    readonly property color gutter: root.dark ? "#3b4261" : "#a8aecb"
+    readonly property color bg: root.palette.bg
+    readonly property color bgDark: root.palette.bgDark
+    readonly property color bgHighlight: root.palette.bgHighlight
+    readonly property color bgPanel: root.palette.bgPanel // dock glass surface
+    readonly property color bgPopover: root.palette.bgPopover // Openbar submenu background
+
+    readonly property color fg: root.palette.fg
+    readonly property color fgDim: root.palette.fgDim
+    readonly property color fgMuted: root.palette.fgMuted
+    readonly property color gutter: root.palette.gutter
+
+    // ── Bar text ────────────────────────────────────────────────────────────
+    // Every other surface in the shell draws on a ground the theme chose. The
+    // bar draws on the wallpaper, which the theme has never seen — so a
+    // photograph with a bright sky can leave the palette's own fg unreadable
+    // exactly where the clock is.
+    //
+    // Hence a second neutral family, used by the bar and nowhere else. Left
+    // alone it *is* the fg family, so nothing changes for anyone who never
+    // asks. Forced light or dark, it becomes a run that survives whatever is
+    // underneath it, and the two dims are mixed toward the opposite end rather
+    // than picked by hand, so the three stay a family either way.
+    readonly property string barTextTone: DesktopPreferences.get("barTextTone")
+
+    readonly property color barFg: {
+        if (root.barTextTone === "light")
+            return "#f4f6ff";
+        if (root.barTextTone === "dark")
+            return "#1b2130";
+        return root.fg;
+    }
+
+    readonly property color barFgDim: {
+        if (root.barTextTone === "light")
+            return root.mix(root.barFg, "#20242f", 0.35);
+        if (root.barTextTone === "dark")
+            return root.mix(root.barFg, "#ffffff", 0.35);
+        return root.fgDim;
+    }
+
+    readonly property color barFgMuted: {
+        if (root.barTextTone === "light")
+            return root.mix(root.barFg, "#20242f", 0.5);
+        if (root.barTextTone === "dark")
+            return root.mix(root.barFg, "#ffffff", 0.5);
+        return root.fgMuted;
+    }

    // ── The accent ──────────────────────────────────────────────────────────
    //
@@ -75,16 +115,16 @@ Singleton {
    // shell-wide colour roles.
    readonly property color accent: root.activeProfile.accent
    readonly property color accentSecondary: root.activeProfile.secondary
-    readonly property color accentAlt: root.dark ? "#65bcff" : "#007197" // blue1, a lighter blue
-    readonly property color cyan: root.dark ? "#86e1fc" : "#007197"
-    readonly property color teal: root.dark ? "#4fd6be" : "#118c74"
-    readonly property color green: root.dark ? "#c3e88d" : "#587539"
-    readonly property color yellow: root.dark ? "#ffc777" : "#8c6c3e"
-    readonly property color orange: root.dark ? "#ff966c" : "#b15c00"
-    readonly property color red: root.dark ? "#ff757f" : "#f52a65"
-    readonly property color redDeep: root.dark ? "#c53b53" : "#c64343"
-    readonly property color magenta: root.dark ? "#c099ff" : "#9854f1"
-    readonly property color pink: root.dark ? "#fca7ea" : "#d20065"
+    readonly property color accentAlt: root.palette.accentAlt
+    readonly property color cyan: root.palette.cyan
+    readonly property color teal: root.palette.teal
+    readonly property color green: root.palette.green
+    readonly property color yellow: root.palette.yellow
+    readonly property color orange: root.palette.orange
+    readonly property color red: root.palette.red
+    readonly property color redDeep: root.palette.redDeep
+    readonly property color magenta: root.palette.magenta
+    readonly property color pink: root.palette.pink

    // Semantic aliases — prefer these in widgets so intent survives a repaint.
    readonly property color ok: green
@@ -164,14 +204,21 @@ Singleton {
    // ── Motion ──────────────────────────────────────────────────────────────
    // Event-driven only. Nothing in this shell animates while idle — no pulse,
    // no shimmer, no spinners. These durations are used for open/close/hover.
-    readonly property int durFast: 120
-    readonly property int durNormal: 200
-    readonly property int durSlow: 320
+    //
+    // All of them collapse to zero when Reduce motion is on: the Accessibility
+    // toggle used to still the compositor's windows while the shell's own bar,
+    // dock and panels kept moving, which made it a half-truth. A duration of 0
+    // is a completed animation, so every Behavior and NumberAnimation in the
+    // shell obeys the switch without knowing it exists.
+    readonly property bool motionEnabled: Settings.animationsEnabled
+    readonly property int durFast: motionEnabled ? 120 : 0
+    readonly property int durNormal: motionEnabled ? 200 : 0
+    readonly property int durSlow: motionEnabled ? 320 : 0

    // The dock revealing is the one animation that answers a live pointer
    // movement, so it gets its own (much shorter) duration. Anything slower
    // reads as the desktop lagging behind the cursor rather than as motion.
-    readonly property int durDockReveal: 90
+    readonly property int durDockReveal: motionEnabled ? 90 : 0

    // Matches the "snappy" spring curve defined in hypr/looks.lua.
    readonly property list<real> easeStandard: [0.05, 0.9, 0.1, 1.0]
@@ -0,0 +1,70 @@
+{
+  "_comment": "Generated-by-hand source of truth for every consumer outside QML. See config/dot/quickshell/config/PALETTE.md.",
+  "default": "blue",
+  "accents": {
+    "blue": {
+      "dark": "82aaff",
+      "darkSecondary": "b172b0",
+      "light": "2e7de9",
+      "lightSecondary": "9854f1",
+      "label": "Prism blue",
+      "gnome": "blue"
+    },
+    "orchid": {
+      "dark": "c099ff",
+      "darkSecondary": "fca7ea",
+      "light": "7847bd",
+      "lightSecondary": "9854f1",
+      "label": "Orchid",
+      "gnome": "purple"
+    },
+    "teal": {
+      "dark": "86e1fc",
+      "darkSecondary": "82aaff",
+      "light": "007197",
+      "lightSecondary": "2e7de9",
+      "label": "Teal",
+      "gnome": "teal"
+    },
+    "green": {
+      "dark": "c3e88d",
+      "darkSecondary": "86e1fc",
+      "light": "587539",
+      "lightSecondary": "007197",
+      "label": "Green",
+      "gnome": "green"
+    },
+    "amber": {
+      "dark": "ffc777",
+      "darkSecondary": "ff966c",
+      "light": "8c6c3e",
+      "lightSecondary": "b15c00",
+      "label": "Amber",
+      "gnome": "yellow"
+    },
+    "orange": {
+      "dark": "ff966c",
+      "darkSecondary": "ff757f",
+      "light": "b15c00",
+      "lightSecondary": "c64343",
+      "label": "Orange",
+      "gnome": "orange"
+    },
+    "rose": {
+      "dark": "ff757f",
+      "darkSecondary": "c099ff",
+      "light": "f52a65",
+      "lightSecondary": "9854f1",
+      "label": "Rose",
+      "gnome": "red"
+    },
+    "slate": {
+      "dark": "828bb8",
+      "darkSecondary": "82aaff",
+      "light": "6172b0",
+      "lightSecondary": "2e7de9",
+      "label": "Slate",
+      "gnome": "slate"
+    }
+  }
+}
@@ -0,0 +1,217 @@
+{
+  "comment": "The shipped theme catalog — the one source of truth for full palettes. services/ThemeCatalog.qml reads it with FileView, scripts read it with jq, contracts read it with fs. The 19 palette keys are exactly Theme.qml's color tokens; ansi's 16 feed generated terminal themes. moon and day must stay byte-identical to the shell's pre-theme literals: theme-catalog-contract pins that.",
+  "defaultDark": "moon",
+  "defaultLight": "day",
+  "themes": [
+    {
+      "id": "moon", "name": "Tokyo Moon", "scheme": "dark",
+      "accent": "#82aaff", "secondary": "#b172b0",
+      "palette": {
+        "bg": "#222436", "bgDark": "#1e2030", "bgHighlight": "#2f334d",
+        "bgPanel": "#2e2f3d", "bgPopover": "#21212f",
+        "fg": "#c8d3f5", "fgDim": "#828bb8", "fgMuted": "#636da6",
+        "gutter": "#3b4261", "accentAlt": "#65bcff",
+        "cyan": "#86e1fc", "teal": "#4fd6be", "green": "#c3e88d",
+        "yellow": "#ffc777", "orange": "#ff966c", "red": "#ff757f",
+        "redDeep": "#c53b53", "magenta": "#c099ff", "pink": "#fca7ea"
+      },
+      "ansi": {
+        "black": "#1b1d2b", "red": "#ff757f", "green": "#c3e88d",
+        "yellow": "#ffc777", "blue": "#82aaff", "magenta": "#c099ff",
+        "cyan": "#86e1fc", "white": "#828bb8",
+        "brightBlack": "#444a73", "brightRed": "#ff8d94", "brightGreen": "#c7fb6d",
+        "brightYellow": "#ffd8ab", "brightBlue": "#9ab8ff", "brightMagenta": "#caabff",
+        "brightCyan": "#b2ebff", "brightWhite": "#c8d3f5"
+      }
+    },
+    {
+      "id": "moon-rose", "name": "Moon Rose", "scheme": "dark",
+      "accent": "#ff757f", "secondary": "#c099ff",
+      "palette": {
+        "bg": "#222436", "bgDark": "#1e2030", "bgHighlight": "#2f334d",
+        "bgPanel": "#2e2f3d", "bgPopover": "#21212f",
+        "fg": "#c8d3f5", "fgDim": "#828bb8", "fgMuted": "#636da6",
+        "gutter": "#3b4261", "accentAlt": "#fca7ea",
+        "cyan": "#86e1fc", "teal": "#4fd6be", "green": "#c3e88d",
+        "yellow": "#ffc777", "orange": "#ff966c", "red": "#ff757f",
+        "redDeep": "#c53b53", "magenta": "#c099ff", "pink": "#fca7ea"
+      },
+      "ansi": {
+        "black": "#1b1d2b", "red": "#ff757f", "green": "#c3e88d",
+        "yellow": "#ffc777", "blue": "#82aaff", "magenta": "#c099ff",
+        "cyan": "#86e1fc", "white": "#828bb8",
+        "brightBlack": "#444a73", "brightRed": "#ff8d94", "brightGreen": "#c7fb6d",
+        "brightYellow": "#ffd8ab", "brightBlue": "#9ab8ff", "brightMagenta": "#caabff",
+        "brightCyan": "#b2ebff", "brightWhite": "#c8d3f5"
+      }
+    },
+    {
+      "id": "mocha", "name": "Catppuccin Mocha", "scheme": "dark",
+      "accent": "#cba6f7", "secondary": "#f5c2e7",
+      "palette": {
+        "bg": "#1e1e2e", "bgDark": "#181825", "bgHighlight": "#313244",
+        "bgPanel": "#27273a", "bgPopover": "#1b1b2a",
+        "fg": "#cdd6f4", "fgDim": "#9399b2", "fgMuted": "#7f849c",
+        "gutter": "#45475a", "accentAlt": "#89dceb",
+        "cyan": "#89dceb", "teal": "#94e2d5", "green": "#a6e3a1",
+        "yellow": "#f9e2af", "orange": "#fab387", "red": "#f38ba8",
+        "redDeep": "#b04a5a", "magenta": "#cba6f7", "pink": "#f5c2e7"
+      },
+      "ansi": {
+        "black": "#45475a", "red": "#f38ba8", "green": "#a6e3a1",
+        "yellow": "#f9e2af", "blue": "#89b4fa", "magenta": "#f5c2e7",
+        "cyan": "#94e2d5", "white": "#bac2de",
+        "brightBlack": "#585b70", "brightRed": "#f38ba8", "brightGreen": "#a6e3a1",
+        "brightYellow": "#f9e2af", "brightBlue": "#89b4fa", "brightMagenta": "#f5c2e7",
+        "brightCyan": "#94e2d5", "brightWhite": "#a6adc8"
+      }
+    },
+    {
+      "id": "nord", "name": "Nord", "scheme": "dark",
+      "accent": "#88c0d0", "secondary": "#81a1c1",
+      "palette": {
+        "bg": "#2e3440", "bgDark": "#272c36", "bgHighlight": "#3b4252",
+        "bgPanel": "#353c4a", "bgPopover": "#2a303c",
+        "fg": "#d8dee9", "fgDim": "#9aa4b8", "fgMuted": "#7b8598",
+        "gutter": "#4c566a", "accentAlt": "#8fbcbb",
+        "cyan": "#88c0d0", "teal": "#8fbcbb", "green": "#a3be8c",
+        "yellow": "#ebcb8b", "orange": "#d08770", "red": "#bf616a",
+        "redDeep": "#a54e57", "magenta": "#b48ead", "pink": "#c9a3c0"
+      },
+      "ansi": {
+        "black": "#3b4252", "red": "#bf616a", "green": "#a3be8c",
+        "yellow": "#ebcb8b", "blue": "#81a1c1", "magenta": "#b48ead",
+        "cyan": "#88c0d0", "white": "#e5e9f0",
+        "brightBlack": "#4c566a", "brightRed": "#bf616a", "brightGreen": "#a3be8c",
+        "brightYellow": "#ebcb8b", "brightBlue": "#81a1c1", "brightMagenta": "#b48ead",
+        "brightCyan": "#8fbcbb", "brightWhite": "#eceff4"
+      }
+    },
+    {
+      "id": "gruvbox", "name": "Gruvbox", "scheme": "dark",
+      "accent": "#fabd2f", "secondary": "#fe8019",
+      "palette": {
+        "bg": "#282828", "bgDark": "#1d2021", "bgHighlight": "#3c3836",
+        "bgPanel": "#32302f", "bgPopover": "#211f1e",
+        "fg": "#ebdbb2", "fgDim": "#a89984", "fgMuted": "#928374",
+        "gutter": "#504945", "accentAlt": "#83a598",
+        "cyan": "#83a598", "teal": "#8ec07c", "green": "#b8bb26",
+        "yellow": "#fabd2f", "orange": "#fe8019", "red": "#fb4934",
+        "redDeep": "#cc241d", "magenta": "#d3869b", "pink": "#dfa7be"
+      },
+      "ansi": {
+        "black": "#282828", "red": "#cc241d", "green": "#98971a",
+        "yellow": "#d79921", "blue": "#458588", "magenta": "#b16286",
+        "cyan": "#689d6a", "white": "#a89984",
+        "brightBlack": "#928374", "brightRed": "#fb4934", "brightGreen": "#b8bb26",
+        "brightYellow": "#fabd2f", "brightBlue": "#83a598", "brightMagenta": "#d3869b",
+        "brightCyan": "#8ec07c", "brightWhite": "#ebdbb2"
+      }
+    },
+    {
+      "id": "everforest", "name": "Everforest", "scheme": "dark",
+      "accent": "#a7c080", "secondary": "#e69875",
+      "palette": {
+        "bg": "#2d353b", "bgDark": "#272e33", "bgHighlight": "#3d484d",
+        "bgPanel": "#343f44", "bgPopover": "#293136",
+        "fg": "#d3c6aa", "fgDim": "#9da9a0", "fgMuted": "#7a8478",
+        "gutter": "#475258", "accentAlt": "#7fbbb3",
+        "cyan": "#7fbbb3", "teal": "#83c092", "green": "#a7c080",
+        "yellow": "#dbbc7f", "orange": "#e69875", "red": "#e67e80",
+        "redDeep": "#c05a5e", "magenta": "#d699b6", "pink": "#dfa7c1"
+      },
+      "ansi": {
+        "black": "#3d484d", "red": "#e67e80", "green": "#a7c080",
+        "yellow": "#dbbc7f", "blue": "#7fbbb3", "magenta": "#d699b6",
+        "cyan": "#83c092", "white": "#d3c6aa",
+        "brightBlack": "#475258", "brightRed": "#e67e80", "brightGreen": "#a7c080",
+        "brightYellow": "#dbbc7f", "brightBlue": "#7fbbb3", "brightMagenta": "#d699b6",
+        "brightCyan": "#83c092", "brightWhite": "#d3c6aa"
+      }
+    },
+    {
+      "id": "day", "name": "Tokyo Day", "scheme": "light",
+      "accent": "#2e7de9", "secondary": "#9854f1",
+      "palette": {
+        "bg": "#e1e2e7", "bgDark": "#d3d5de", "bgHighlight": "#c4c8da",
+        "bgPanel": "#d9dae3", "bgPopover": "#eaeaee",
+        "fg": "#3760bf", "fgDim": "#6172b0", "fgMuted": "#848cb5",
+        "gutter": "#a8aecb", "accentAlt": "#007197",
+        "cyan": "#007197", "teal": "#118c74", "green": "#587539",
+        "yellow": "#8c6c3e", "orange": "#b15c00", "red": "#f52a65",
+        "redDeep": "#c64343", "magenta": "#9854f1", "pink": "#d20065"
+      },
+      "ansi": {
+        "black": "#b4b5b9", "red": "#f52a65", "green": "#587539",
+        "yellow": "#8c6c3e", "blue": "#2e7de9", "magenta": "#9854f1",
+        "cyan": "#007197", "white": "#6172b0",
+        "brightBlack": "#a1a6c5", "brightRed": "#ff4774", "brightGreen": "#5c8524",
+        "brightYellow": "#a27629", "brightBlue": "#358aff", "brightMagenta": "#a463ff",
+        "brightCyan": "#007ea8", "brightWhite": "#3760bf"
+      }
+    },
+    {
+      "id": "latte", "name": "Catppuccin Latte", "scheme": "light",
+      "accent": "#8839ef", "secondary": "#ea76cb",
+      "palette": {
+        "bg": "#eff1f5", "bgDark": "#e6e9ef", "bgHighlight": "#ccd0da",
+        "bgPanel": "#e2e6ee", "bgPopover": "#f5f7fa",
+        "fg": "#4c4f69", "fgDim": "#6c6f85", "fgMuted": "#8c8fa1",
+        "gutter": "#acb0be", "accentAlt": "#209fb5",
+        "cyan": "#04a5e5", "teal": "#179299", "green": "#40a02b",
+        "yellow": "#df8e1d", "orange": "#fe640b", "red": "#d20f39",
+        "redDeep": "#e64553", "magenta": "#8839ef", "pink": "#ea76cb"
+      },
+      "ansi": {
+        "black": "#5c5f77", "red": "#d20f39", "green": "#40a02b",
+        "yellow": "#df8e1d", "blue": "#1e66f5", "magenta": "#ea76cb",
+        "cyan": "#179299", "white": "#acb0be",
+        "brightBlack": "#6c6f85", "brightRed": "#d20f39", "brightGreen": "#40a02b",
+        "brightYellow": "#df8e1d", "brightBlue": "#1e66f5", "brightMagenta": "#ea76cb",
+        "brightCyan": "#179299", "brightWhite": "#bcc0cc"
+      }
+    },
+    {
+      "id": "gruvbox-light", "name": "Gruvbox Light", "scheme": "light",
+      "accent": "#b57614", "secondary": "#af3a03",
+      "palette": {
+        "bg": "#fbf1c7", "bgDark": "#f2e5bc", "bgHighlight": "#ebdbb2",
+        "bgPanel": "#f0e6c0", "bgPopover": "#fdf6d8",
+        "fg": "#3c3836", "fgDim": "#665c54", "fgMuted": "#7c6f64",
+        "gutter": "#bdae93", "accentAlt": "#076678",
+        "cyan": "#076678", "teal": "#427b58", "green": "#79740e",
+        "yellow": "#b57614", "orange": "#af3a03", "red": "#9d0006",
+        "redDeep": "#cc241d", "magenta": "#8f3f71", "pink": "#b16286"
+      },
+      "ansi": {
+        "black": "#fbf1c7", "red": "#cc241d", "green": "#98971a",
+        "yellow": "#d79921", "blue": "#458588", "magenta": "#b16286",
+        "cyan": "#689d6a", "white": "#7c6f64",
+        "brightBlack": "#928374", "brightRed": "#9d0006", "brightGreen": "#79740e",
+        "brightYellow": "#b57614", "brightBlue": "#076678", "brightMagenta": "#8f3f71",
+        "brightCyan": "#427b58", "brightWhite": "#3c3836"
+      }
+    },
+    {
+      "id": "everforest-light", "name": "Everforest Light", "scheme": "light",
+      "accent": "#8da101", "secondary": "#f57d26",
+      "palette": {
+        "bg": "#fdf6e3", "bgDark": "#f4f0d9", "bgHighlight": "#e6e2cc",
+        "bgPanel": "#efebd4", "bgPopover": "#faf3dc",
+        "fg": "#5c6a72", "fgDim": "#829181", "fgMuted": "#939f91",
+        "gutter": "#a6b0a0", "accentAlt": "#3a94c5",
+        "cyan": "#3a94c5", "teal": "#35a77c", "green": "#8da101",
+        "yellow": "#dfa000", "orange": "#f57d26", "red": "#f85552",
+        "redDeep": "#e66868", "magenta": "#df69ba", "pink": "#df69ba"
+      },
+      "ansi": {
+        "black": "#5c6a72", "red": "#f85552", "green": "#8da101",
+        "yellow": "#dfa000", "blue": "#3a94c5", "magenta": "#df69ba",
+        "cyan": "#35a77c", "white": "#e0dcc7",
+        "brightBlack": "#829181", "brightRed": "#f85552", "brightGreen": "#8da101",
+        "brightYellow": "#dfa000", "brightBlue": "#3a94c5", "brightMagenta": "#df69ba",
+        "brightCyan": "#35a77c", "brightWhite": "#fdf6e3"
+      }
+    }
+  ]
+}
@@ -75,6 +75,36 @@ ShellRoot {
            })));
        }

+        // One display is the common case on a laptop, and the canvas is the
+        // page's hero now: it renders that display rather than disappearing and
+        // leaving a picker for a list of one. Only dragging goes away, because
+        // there is nothing to arrange it against.
+        function soloFixture(): string {
+            const previous = fixtureService.monitors;
+            fixtureService.monitors = [previous[0]];
+            arrangement.resetDraft();
+            const snapshot = arrangement.canvasSnapshot();
+            fixtureService.monitors = previous;
+            arrangement.resetDraft();
+            return JSON.stringify(snapshot);
+        }
+
+        // A mirrored display has no position of its own -- the compositor puts
+        // it on top of its target -- so the canvas stacks it there and says so
+        // rather than drawing it wherever its stale coordinates point.
+        function mirrorFixture(): string {
+            const previous = fixtureService.monitors;
+            fixtureService.monitors = [
+                previous[0],
+                Object.assign({}, previous[1], { mirrorOf: "DP-2" })
+            ];
+            arrangement.resetDraft();
+            const snapshot = arrangement.canvasSnapshot();
+            fixtureService.monitors = previous;
+            arrangement.resetDraft();
+            return JSON.stringify(snapshot);
+        }
+
        function identify(): void { Displays.identify(); }
        function identifying(): bool { return Displays.identifying; }
    }
@@ -10,9 +10,53 @@ ShellRoot {
        { name: "HDMI-A-1", width: 2560, height: 1440, scale: 1, transform: 1, x: 3140, y: 80, primary: false }
    ]

+    // The same two displays, with the second mirroring the first. A mirrored
+    // display has no position of its own: the compositor puts it on top of its
+    // target, so its stored coordinates are stale the moment mirroring is on.
+    readonly property var mirrored: [
+        { name: "DP-2", width: 4500, height: 3000, scale: 1.5, transform: 0, x: 140, y: 80, primary: true, mirrorOf: "" },
+        { name: "HDMI-A-1", width: 2560, height: 1440, scale: 1, transform: 0, x: 3140, y: 80, primary: false, mirrorOf: "DP-2" }
+    ]
+
    IpcHandler {
        target: "display-layout-test"

+        function mirror(): string {
+            const normalized = DisplayLayout.normalize(mirrored);
+            const canvas = DisplayLayout.canvasRects(normalized, 800, 500, 20);
+            return JSON.stringify({
+                valid: DisplayLayout.validate(mirrored),
+                normalized: normalized.map(record => ({
+                    name: record.name, x: record.x, y: record.y,
+                    primary: record.primary, mirrorOf: record.mirrorOf ?? ""
+                })),
+                bounds: canvas.bounds,
+                rects: canvas.rects
+            });
+        }
+
+        function invalidMirrors(): string {
+            const base = mirrored.map(record => Object.assign({}, record));
+            const cases = [];
+            const add = layout => cases.push(DisplayLayout.validate(layout));
+            // Mirroring itself.
+            add([base[0], Object.assign({}, base[1], { mirrorOf: "HDMI-A-1" })]);
+            // Mirroring an output that is not in the layout.
+            add([base[0], Object.assign({}, base[1], { mirrorOf: "NOPE-1" })]);
+            // The primary may not mirror: the desktop is anchored on it.
+            add([Object.assign({}, base[0], { mirrorOf: "HDMI-A-1" }), base[1]]);
+            // No chains. Hyprland resolves a mirror to one target, and a chain
+            // is a question nobody can answer from the canvas.
+            add([
+                base[0],
+                Object.assign({}, base[1], { mirrorOf: "DP-3" }),
+                { name: "DP-3", width: 1920, height: 1080, scale: 1, transform: 0, x: 6000, y: 0, primary: false, mirrorOf: "DP-2" }
+            ]);
+            // Not a name at all.
+            add([base[0], Object.assign({}, base[1], { mirrorOf: 5 })]);
+            return JSON.stringify(cases);
+        }
+
        function status(): string {
            const normalized = DisplayLayout.normalize(fixture);
            const canvas = DisplayLayout.canvasRects(normalized, 800, 500, 20);
@@ -32,7 +32,14 @@ ShellRoot {
                canConfirm: Displays.canConfirm,
                secondsLeft: Displays.secondsLeft,
                lastError: Displays.lastError,
-                overridden: monitor ? Displays.isOverridden(monitor.name) : false
+                overridden: monitor ? Displays.isOverridden(monitor.name) : false,
+                // The compositor being visually restored is not the service
+                // being done: revert verification keeps its own readback
+                // running for a few ticks, and busy blocks a new apply until
+                // it settles. A caller that only watched `awaiting` raced
+                // this and got a refusal with no error text.
+                settled: !Displays.busy && !Displays.revertVerificationActive
+                    && !Displays.awaitingConfirmation
            });
        }

@@ -79,6 +86,56 @@ ShellRoot {
            Displays.parse(text, generation);
        }

+        // The restore-on-reconnect decision, without applying anything. The
+        // caller injects a topology with injectReadback first, sets the stored
+        // arrangement here, and reads back what Panama would do about it.
+        // Both arguments are base64. `qs ipc call` splits an argument that
+        // looks like a JSON array of several objects into one argument per
+        // object, so a two-monitor fixture arrives as two arguments and the
+        // call is rejected for arity. Encoding sidesteps the parsing entirely.
+        //
+        // Topology and stored arrangement are set in one call on purpose: a
+        // real compositor query landing between two calls would replace the
+        // injected topology, and the answer would be about this machine's
+        // actual monitor instead of the fixture.
+        function restorePlan(readbackB64: string, storedB64: string): string {
+            Displays.parse(Qt.atob(readbackB64), 0);
+            DesktopPreferences.set("displays", JSON.parse(Qt.atob(storedB64)));
+            const plan = Displays.plannedRestore();
+            return JSON.stringify({
+                action: plan.action,
+                layout: (plan.layout ?? []).map(record => ({
+                    name: record.name, mode: record.mode, scale: record.scale,
+                    transform: record.transform, x: record.x, y: record.y,
+                    primary: record.primary
+                }))
+            });
+        }
+
+        // The extended record — vrr override, colour profile, bit depth, SDR
+        // trim, mirroring — merged one field at a time, which is how every
+        // control on the page changes it. Base64 for the reason restorePlan
+        // documents above: `qs ipc call` splits JSON that looks like an array
+        // of objects into one argument per object.
+        function applyRecordFixture(output: string, patchB64: string): bool {
+            return Displays.applyRecord(output, JSON.parse(Qt.atob(patchB64)));
+        }
+
+        // matchesLayout as a pure function. The readback carve-outs — a
+        // mirrored output's position, a framebuffer format Panama does not
+        // recognise — are decisions about what NOT to assert, and proving them
+        // through a compositor would mean owning a compositor that mirrors.
+        function layoutMatch(monitorsB64: string, layoutB64: string): bool {
+            return Displays.matchesLayout(JSON.parse(Qt.atob(monitorsB64)),
+                JSON.parse(Qt.atob(layoutB64)));
+        }
+
+        // A settings.json written before any of the new fields existed is the
+        // common case on every machine that has this installed today.
+        function persistedEntryValid(entryB64: string): bool {
+            return Displays.isPersistedLayoutEntry(JSON.parse(Qt.atob(entryB64)));
+        }
+
        function expireApplyVerification(): void {
            Displays.verificationTimedOut();
        }
@@ -19,5 +19,9 @@ ShellRoot {
        function repair(id: string): bool { return Health.repair(id, false); }
        function report(): string { return JSON.stringify(Health.snapshot, null, 2); }
        function copy(): bool { return Health.copyReport(); }
+        // Both take an explicit destination or subject, so nothing here writes
+        // to the real home or rescans anything the fixture did not ask for.
+        function save(path: string): bool { return Health.saveReport(path); }
+        function recheck(id: string): bool { return Health.refreshCheck(id); }
    }
 }
@@ -0,0 +1,80 @@
+# Coming from another desktop
+
+Panama is Hyprland with a shell built to replace a GNOME session, so most of
+what you know still applies. The differences worth knowing on day one are
+below. Nothing here is a preference you have to accept: every one of them is
+adjustable in Settings.
+
+## Windows arrange themselves
+
+The biggest change. You do not drag windows into position. Open a second
+window and the screen splits; open a third and it splits again. This is
+called tiling, and after a day of it, dragging windows feels like making
+your own bed in a hotel.
+
+Two things follow from it:
+
+- **There is no minimise.** A minimised window is a window you have hidden
+  from a layout that was managing it for you. Use `Super + Shift + X` to
+  push a window to the scratchpad and `Super + X` to bring it back, which is
+  the same idea without the layout losing track of it.
+- **Floating still exists.** `Super + Ctrl + C` makes a window float above
+  the layout, for the dialog that was never meant to be tiled.
+
+## Workspaces replace the taskbar
+
+Instead of many windows on one screen, use many screens. `Alt + 1` through
+`Alt + 0` jump straight to a workspace; `Alt + Shift + 1` sends the window
+you are looking at to workspace one. `Super + backtick` shows all of them at
+once.
+
+If you came from macOS, this is Spaces with the friction removed. If you came
+from Windows, it is virtual desktops that are actually worth using because
+switching is one key rather than three.
+
+## The launcher is the menu
+
+There is no applications menu to browse. `Super + Space` opens a search box
+that finds applications, files, clipboard history, emoji, and does
+arithmetic. Type three letters of what you want.
+
+This replaces the Start menu, Spotlight, the GNOME overview's app grid, and
+the run dialog, and it is faster than all of them because it never asks you
+to aim at anything.
+
+## What stayed the same
+
+`Super + Tab` still switches windows. The bar is still along the top with a
+clock in the middle and status on the right. There is still a dock. Volume
+and brightness keys still work, and still work on the lock screen. Copy and
+paste are unchanged. Your files are where you left them.
+
+## Where the settings went
+
+`Super + I` opens Panama's own Settings. The sidebar is where GNOME's panels
+ended up, and it is worth one read so you never have to hunt:
+
+| If you are looking for | It is under |
+|---|---|
+| Themes, wallpaper, fonts, text size, titlebars | Appearance |
+| The bar, the dock, Control Center, tiling, workspaces | Shell |
+| Resolution, scale, arrangement, night light | Displays |
+| Output and input devices, per-application volume | Sound |
+| Do Not Disturb, per-application rules, focus modes | Notifications & Focus |
+| Shortcuts, mouse and touchpad, dictation | Input |
+| Wi-Fi and VPN, the firewall, sharing, printers | Network & Sharing |
+| Default applications, autostart, gaming, Screen Intelligence | Applications |
+| The accounts on this machine, and online ones | Users & Accounts |
+| Permissions, saved passwords, what the machine remembers, SSH keys | Privacy & Security |
+| Battery, the lid, the power button, idle and lock timings | Power & Lock |
+| Magnifier, color filters, reduced motion, screen reader | Accessibility |
+| Updates, storage, snapshots, date and time, backups | System |
+
+Home is the page `Super + I` lands on. The search box above the sidebar
+searches the settings themselves rather than the page names, so typing what you
+want to change is usually faster than remembering which of those it lives in.
+
+GNOME Settings is still installed, and Panama's Settings opens it in exactly
+two places: adding an online account, which has to go through the provider's
+own dialog, and Digital wellbeing, which is the one panel of GNOME's that does
+something Panama does not.
@@ -0,0 +1,66 @@
+# The keyboard
+
+Press `Super + /` at any time to see every shortcut this machine has. That
+list is generated from the live keymap, so it is never out of date, and it
+includes anything you have rebound.
+
+This chapter is the shape behind that list, which is the part worth learning
+once.
+
+## Three modifiers, three jobs
+
+| Modifier | Acts on |
+|---|---|
+| `Super` | The window you are looking at |
+| `Alt` | Workspaces |
+| `Super + Ctrl` | The layout itself: splitting, floating, swapping |
+| `Super + Alt` | The application you already have open |
+
+Almost every shortcut follows from this. `Super + H` moves focus left.
+`Alt + H` moves to the workspace on the left. `Super + Ctrl + H` swaps the
+window leftward in the layout.
+
+## Directions
+
+`H`, `J`, `K`, `L` mean left, down, up, right, as they do in vim. The arrow
+keys work everywhere the letters do, so you never have to learn them if you
+would rather not.
+
+Add `Shift` to move the window rather than the focus. `Super + Shift + L`
+takes the current window and moves it to the right.
+
+## Opening versus going to
+
+`Super + T` opens a terminal. It opens another one every time, which on a
+tiling desktop is the normal way to work rather than an accident.
+
+`Super + Alt + T` goes to a terminal you already have, wherever it is, and
+opens one only if there is none. The same pair works for the editor, browser,
+files, calculator and mail.
+
+So the plain key means "give me one" and adding `Alt` means "take me to the
+one I have".
+
+## The handful worth memorising first
+
+| Keys | What it does |
+|---|---|
+| `Super + Space` | Find and open anything |
+| `Super + T` | Terminal (another one) |
+| `Super + Alt + T` | The terminal you already have |
+| `Super + Q` | Close the window |
+| `Super + backtick` | Every window, every workspace |
+| `Super + I` | Settings |
+| `Super + /` | Every other shortcut |
+
+## Changing them
+
+Settings has a [Keyboard page](panama://settings/shortcuts), under Input, listing every bind, each of which
+can be reassigned. A rebind moves the shortcut and cannot change what it does, so
+there is no way to make a key do something unexpected by editing it.
+
+Shortcuts you invent live in the same list, in a **Custom** group above the
+rest. One of those names an application, a shell action or a window move rather
+than storing a command — for the same reason: what you are choosing is which
+key, not what it runs. A chord something already holds is refused rather than
+stolen, so a new shortcut can never quietly cost you an old one.
@@ -0,0 +1,77 @@
+# Windows and workspaces
+
+## How the split is chosen
+
+A new window splits the space of the window that had focus. Whether it splits
+beside or below depends on which way that space is longer, which usually
+matches what you were about to do anyway.
+
+When it does not, `Super + Ctrl + G` flips the split of the focused window,
+and `Super + Ctrl + Z` and `Super + Ctrl + V` decide the direction the *next*
+window will take before you open it.
+
+## Resizing
+
+`Super + Shift` plus `Y`, `O`, `B`, `M` adjusts width; `I`, `U`, `N` and
+comma adjust height. These are inverted from what their letters suggest, on
+purpose, and the reason is written in `config/dot/hypr/keybinds.lua` next to
+the binds.
+
+For anything finer, hold `Super` and drag with the right mouse button.
+
+## Fullscreen and floating
+
+`Super + U` makes the focused window fullscreen. `Super + Ctrl + C` lifts it
+out of the layout to float, and `Super + Ctrl + Shift + C` pins it so it
+follows you between workspaces. A floating window can be moved by holding
+`Super` and dragging with the left button.
+
+## Workspaces
+
+Ten you can jump straight to, on `Alt + 1` through `Alt + 0`, though they are
+created and destroyed as you use them rather than sitting there empty. `Alt + H`
+and `Alt + L` step between neighbours — right past the last one makes a new one,
+left from the first stays put — and `Alt + Shift` plus a number sends the
+current window somewhere without following it.
+
+On a machine with more than one display, workspaces belong to whichever
+screen has focus. If you would rather pin workspaces one through ten to your
+main display and give the second screen its own, that is a switch on the
+Displays settings page.
+
+How windows share the space — the layout, the master area, gaps and window
+edges — is Shell › Tiling. The workspace switches themselves, and the projects
+below, are Shell › Workspaces.
+
+## The touchpad
+
+Three fingers sideways moves between workspaces and follows your fingers as it
+goes; three fingers up opens the overview and three down closes it. Those are
+GNOME's gestures, reproduced, and they do not move.
+
+Four fingers are yours. Each of the four directions can be given a job — a shell
+action, a window or workspace move — from the same list your own shortcuts pick
+from, on Input › Mouse & Touchpad. Assigning one reloads the compositor, so
+expect a beat of black before it works. Unassigned directions are left alone
+rather than bound to nothing.
+
+## Rules for one application
+
+Some windows want the same treatment every time: the password manager should
+float, chat should open on workspace four, a picture viewer should not be
+resized to fill half the screen. **Application window rules** on Shell › Tiling is where that
+is written down. You pick an application and tick what should happen to it —
+float, center it, pin it to every workspace, give it a fixed size or a
+workspace to open on — rather than writing a match pattern. Panama's own
+surfaces cannot be targeted, and a rule with nothing ticked is refused rather
+than saved as a row you would wonder about later.
+
+## Projects
+
+A project is the set of windows you open together: which applications, which
+workspace each was on, and for a terminal, which directory it was in.
+
+Arrange things the way you want them, then run **Save Layout as Project**
+from the launcher. **Open Project** lays it out again on free workspaces, so
+it never lands on top of what you are already doing. An application that
+refuses to open twice is moved into place rather than launched again.
@@ -0,0 +1,83 @@
+# When something breaks
+
+## Start here
+
+Run **Check System Health** from the launcher, or open
+[System Health](panama://settings/services). It reports what is actually running rather than what was
+installed, and it can repair several things itself.
+
+From a terminal, the same check is `panama doctor`.
+
+## The shell is gone
+
+If the bar and dock disappear, the Quickshell process died. **Restart Desktop
+Shell** from the launcher brings it back. If the launcher is also gone, press
+`Super + Shift + R` for the fallback launcher, which depends on nothing but
+itself and exists for exactly this.
+
+From a terminal: `qs -d` starts the shell again.
+
+## A shortcut stopped working
+
+Check `Super + /` first: if the shortcut shows a different chord than you
+expect, something rebound it. The Keyboard page, under Input in Settings, can
+reset any bind, or all of them at once.
+
+If the whole keymap is missing from that list, the compositor config failed
+to load. `Hyprland --verify-config` says why without touching your session.
+
+## The screen resolution is wrong
+
+Settings has a [Displays page](panama://settings/displays). It opens on a picture of what is connected —
+one display or several — and everything under that picture belongs to
+whichever one you have selected. Every change there reverts itself after
+fifteen seconds unless you confirm it, so a mode your monitor cannot show
+cannot strand you, and that covers color, bit depth and mirroring as well as
+resolution, scale and rotation. If you are already stranded, `hyprctl
+monitors` from a terminal shows what is applied.
+
+## Something asked for a password and I do not know why
+
+Panama's password prompt names the action that asked. If it was started by an
+agent or a script through `panama-sudo`, it also shows a stated reason,
+labelled as an unverified claim, beside the real action.
+
+If you did not expect it at all, cancel. Nothing that needs privileges is
+harmed by being refused.
+
+## A button did nothing except change its wording
+
+That is the button working. Anything in Settings that removes something takes
+two presses: the first arms it, and the row then shows what is about to happen
+beside a **Keep** that backs out. The second press is the one that does it.
+
+Only one button in Settings is armed at a time, so arming a second one disarms
+the first, wherever it was.
+
+## The network I need is not in the list
+
+The Wi-Fi list is what is in range. **Saved networks**, further down
+[Connections](panama://settings/connectivity), is what this machine remembers,
+including the ones nowhere near you — which is where to tidy up a profile you
+want rid of, rather than waiting until you are standing next to it again. A
+network that broadcasts no name is joined with **Join a hidden network…**, at
+the bottom of the list.
+
+Opening a connection shows what it actually got — address, gateway, DNS — and
+is where you give it a fixed address instead when what it got does not work,
+or mark it metered so updates and large downloads wait until you are somewhere
+else.
+
+## After an update, something is not right
+
+`panama migrate` applies repairs this machine has not had yet. It is safe to
+run at any time and does nothing when there is nothing to do.
+
+If an update went badly, [Snapshots](panama://settings/snapshots) under System can roll
+the system back. That tab is only there where btrfs snapshots are configured,
+so if you cannot see it, this machine has none to roll back to.
+
+## Reporting it
+
+`panama doctor` produces a redacted summary suitable for pasting into an
+issue. It deliberately omits tokens, hostnames and account details.
@@ -0,0 +1,161 @@
+# Making it yours
+
+## Settings
+
+`Super + I`. Fourteen categories down the side, covering appearance, displays,
+sound, input, network, power, accounts and the rest. A category with more than
+one subject in it opens a row of tabs above the page, which is where the
+narrower topics live: Printers is a tab of Network & Sharing, Dictation a tab
+of Input, and About, Software Update, Storage, Snapshots, Sync & Backup and
+this manual are tabs of System.
+
+Home is the first of them, and the page `Super + I` lands on. Its Overview tab
+is the one you already know; My Home lists your Home Assistant lights by room
+alongside the accessories Control Center shows, and Phone holds the iPhone
+handoffs — battery, ring it, send it the clipboard or a file, and Messages.
+
+The search box at the top searches the settings themselves rather than page
+names, and each result says where it will land, so if you know what you want
+to change you can type it and never touch the sidebar.
+
+## Appearance
+
+The Appearance page opens on **Themes**. At the top are light and dark, side by
+side, each showing the theme it will land on; below them are two galleries —
+six dark themes and four light ones, including Catppuccin, Nord, Gruvbox and
+Everforest alongside Panama's own Tokyo Night Moon and Day.
+
+Light and dark remember separately. Pick Everforest for the dark side and
+Catppuccin Latte for the light one, and flipping between them lands on each
+rather than resetting to the shipped pair.
+
+Choosing a theme repaints the shell, the terminal, GTK applications, the lock
+screen and the system monitor at once — not just the shell's own windows.
+
+### Build your own
+
+The **Theme editor** tab is four colors: primary, secondary, background and
+foreground. Each has a swatch, a hex field you can type into, a color wheel
+and an eyedropper for sampling anything on screen. Background and foreground
+are not single colors — the panels, popovers, dividers and dimmed text are all
+mixed from them, so moving the background moves the whole family with it.
+
+Under that, a saturation slider for the whole palette at once, a fine-tune for
+the exact hue of each end of the accent, and the effects — corners, blur,
+shadows, glow and motion. Save it with a name and it appears in the galleries
+above beside the shipped ones, effects included. Editing a shipped theme does
+not damage it: it makes you a copy.
+
+### Wallpapers
+
+The wallpaper is per-monitor if you want it to be, and it can be a video.
+
+Videos loop muted and decode on the GPU. They pause themselves while a game is
+running, and on battery unless you say otherwise; while one is playing a pill
+appears in the bar, and clicking it pauses immediately — for a call, a
+recording, or just quiet. The lock screen shows a still frame from the video,
+because it cannot play motion.
+
+### Titlebars
+
+There is no minimize button, on Panama's windows or on GNOME applications.
+Hyprland has no minimize, so the button would do nothing; maximize means very
+little in a tiler. You get close, on whichever side you prefer. Panama's own
+titlebar can be turned off entirely, which leaves the Settings window bare:
+`Super + Q` closes it, `Super + drag` moves it, `Escape` still works.
+
+## Shell
+
+Everything Panama draws on the screen has a tab under **Shell**: the bar, the
+dock, Control Center, tiling and workspaces. Appearance decides the colors;
+this decides what is there at all.
+
+### The bar
+
+The bar has no background of its own — it floats on your wallpaper. That is
+fine over most images and hopeless over a few, so the **Bar** tab opens on the
+three controls that fix it. **Bar text** follows your theme by default, or you
+can force it light or dark for the wallpaper you actually use. **Bar text
+shadow** puts a soft halo under every glyph at once. **Bar backdrop** fades a
+thin scrim down from the top edge. All three land on the real bar above the
+window as you change them, so you can watch rather than guess.
+
+Under that, one switch per widget: weather, media, the clipboard button, the
+calendar countdown, processor, memory, graphics, battery and agent usage. A
+switch only ever removes something — turning weather on does not make a
+forecast appear before one has been fetched. The indicators that come and go on
+their own — system health, microphone and camera, focus, a paused video
+wallpaper — have no switches, because they are already absent whenever they
+have nothing to say.
+
+Seconds and the weekday are here too. **24-hour time** is not: it also changes
+the date menu, your notification timestamps and the lock screen, so it lives on
+System › Date & Time with the rest of the clock.
+
+### The dock
+
+**Pinned applications** shows the dock as the dock shows it. Drag an icon to
+move it, hover one for the × that unpins it, and search underneath to add
+something. The order here is the order on screen.
+
+The dock itself takes the same gestures now. Drag an icon along the dock to
+reorder it without opening Settings at all. Right-click one for its menu: every
+open window of that application listed by title, whatever shortcuts the
+application itself offers, then a new window, pin or unpin, quit, and **Dock
+settings** if you want the rest. Scroll on an icon to step through that
+application's windows. Hover one that has windows open and a preview of each
+appears after a moment.
+
+For pinning something that is not running, the launcher has **Add App to
+Dock** — type it into `Super + Space`, pick the application, done.
+
+### Control Center
+
+The panel that opens from the status cluster at the right of the bar. The
+**Control Center** tab turns its sections on and off: Focus, Home and Phone.
+Hiding one only hides it from the panel; the settings page behind it still
+works.
+
+### Tiling and workspaces
+
+The last two tabs hold what used to be spread across the old Desktop page.
+**Tiling** is the window layout, the master area, gaps and window edges, and
+the Hyprland notices Panama keeps quiet. **Workspaces** is the workspace
+behaviour, how long a focus session runs, and your saved projects.
+
+## Carrying settings between machines
+
+System › **[Sync & Backup](panama://settings/sync)**. Export writes your settings to a file; importing
+one shows you exactly what would change before anything does, and you decide
+then. Below it, **Settings backups** keeps dated copies you can restore from —
+these are your settings, not btrfs Snapshots, which is a different tab and
+covers the whole filesystem. **Restore defaults** is at the bottom: it resets
+appearance, the dock and the applications pinned to it, clock, focus and
+display policy, removes any themes you saved, and clears your Home accessory
+arrangement. Your files, paired devices and settings backups are left alone.
+
+## Applications
+
+`panama apps` in a terminal offers the optional application categories the
+installer asked about, so a machine can acquire Slack in March without having
+wanted Discord in January.
+
+`panama app` builds the handful of applications no repository carries. It is
+deliberately not part of installing, because a source build is slow and
+depends on an upstream that moves.
+
+## Autostart and defaults
+
+The Applications settings page controls which application opens which kind of
+file, and what starts when you log in.
+
+## Going further
+
+The compositor is configured in Lua under `~/.config/hypr`, and every file
+there explains what it does and why. `overrides.lua` is loaded last and is
+the intended place for per-machine changes, so you can adjust anything
+without editing a file the repository will update.
+
+The shell is QML under `~/.config/quickshell`. Both directories are symlinks
+into the Panama repository, so an edit is a change to your checkout and
+`panama sync` will offer to commit it.
@@ -36,7 +36,7 @@ Pill {
        anchors.verticalCenter: parent.verticalCenter
        visible: PrivacyState.activeKinds.length > 1
        text: String(PrivacyState.activeKinds.length)
-        color: Theme.fg
+        color: Theme.barFg
        font.family: Theme.fontFamily
        font.features: Theme.tabularFigures
        font.pixelSize: Theme.fontSizeSmall
@@ -0,0 +1,592 @@
+// The whole story behind the bar's one number.
+//
+// The bar shows the fullest window across every agent, because that is the one
+// about to interrupt you. This is what that number is made of: each agent's
+// limits with their reset times, what today cost, and where the tokens went.
+//
+// A Popover anchored under the widget, the way TrayMenu hangs off a tray icon —
+// the house pattern for anything that belongs to a bar item rather than to the
+// shell. Clicking outside closes it; so does Escape, which Popover's focus grab
+// handles for every popover in the shell.
+//
+// Nothing in here animates on a timer. One 30-second tick advances the clock
+// that "updated 4 minutes ago" and the reset countdowns read, and it only runs
+// while the panel is open.
+
+import QtQuick
+import qs.config
+import qs.services
+import qs.widgets
+
+Popover {
+    id: root
+
+    implicitWidth: Theme.popoverWidth
+    implicitHeight: body.implicitHeight + contentPadding * 2
+
+    // Which agent's tab is showing. Empty means "whichever is first", so the
+    // panel is never blank because a collector was switched off between opens.
+    property string selectedId: ""
+
+    readonly property var agents: AgentUsage.readyRecords
+
+    readonly property var record: {
+        const list = root.agents;
+        if (list.length === 0)
+            return null;
+        for (const candidate of list)
+            if (candidate.id === root.selectedId)
+                return candidate;
+        return list[0];
+    }
+
+    // One clock for the whole panel, ticking only while it is open. Every
+    // elapsed-time and countdown string in here reads this instead of calling
+    // Date.now() in a binding, which would never invalidate.
+    property double nowMs: Date.now()
+
+    onVisibleChanged: {
+        if (root.visible) {
+            root.nowMs = Date.now();
+            // The local scans can be reused; the limits are what the panel is
+            // being opened to read.
+            AgentUsage.refreshLimits();
+        }
+    }
+
+    Timer {
+        interval: 30 * 1000
+        running: root.visible
+        repeat: true
+        onTriggered: root.nowMs = Date.now()
+    }
+
+    // ── Formatting ──────────────────────────────────────────────────────────
+
+    function tokenText(value: double): string {
+        const n = Number(value) || 0;
+        if (n >= 1e9)
+            return (n / 1e9).toFixed(1) + "B";
+        if (n >= 1e6)
+            return (n / 1e6).toFixed(1) + "M";
+        if (n >= 1e3)
+            return Math.round(n / 1e3) + "k";
+        return String(Math.round(n));
+    }
+
+    function percentText(fraction: real): string {
+        return Math.round(Math.min(1, Math.max(0, Number(fraction) || 0)) * 100) + "%";
+    }
+
+    function meterColor(fraction: real): color {
+        const percent = (Number(fraction) || 0) * 100;
+        if (percent >= 90)
+            return Theme.danger;
+        if (percent >= 75)
+            return Theme.warn;
+        return Theme.accent;
+    }
+
+    function parseTime(iso: string): double {
+        const parsed = Date.parse(String(iso ?? ""));
+        return isNaN(parsed) ? 0 : parsed;
+    }
+
+    // "Updated 4 minutes ago". A record with no timestamp says so rather than
+    // implying it is current.
+    function agoText(iso: string): string {
+        const at = root.parseTime(iso);
+        if (at <= 0)
+            return "Never collected";
+        const minutes = Math.floor(Math.max(0, root.nowMs - at) / 60000);
+        if (minutes < 1)
+            return "Updated just now";
+        if (minutes === 1)
+            return "Updated 1 minute ago";
+        if (minutes < 60)
+            return `Updated ${minutes} minutes ago`;
+        const hours = Math.floor(minutes / 60);
+        return hours === 1 ? "Updated 1 hour ago" : `Updated ${hours} hours ago`;
+    }
+
+    // "resets 2:40 pm" for something today, "resets Thu" for something further
+    // out. A window whose reset has passed says so rather than counting into
+    // the negative — the collector keeps a cached limit only until its window
+    // rolls over, so this is a record caught mid-rollover.
+    function resetText(iso: string): string {
+        const at = root.parseTime(iso);
+        if (at <= 0)
+            return "";
+        if (at <= root.nowMs)
+            return "resetting";
+        const when = new Date(at);
+        const sameDay = new Date(root.nowMs).toDateString() === when.toDateString();
+        if (sameDay)
+            return "resets " + when.toLocaleTimeString(Qt.locale(), "h:mm ap");
+        return "resets " + when.toLocaleDateString(Qt.locale(), "ddd");
+    }
+
+    function weekdayText(date: string): string {
+        const parts = String(date ?? "").split("-");
+        if (parts.length !== 3)
+            return "";
+        const when = new Date(Number(parts[0]), Number(parts[1]) - 1, Number(parts[2]));
+        return when.toLocaleDateString(Qt.locale(), "ddd").slice(0, 2);
+    }
+
+    function isToday(date: string): bool {
+        const parts = String(date ?? "").split("-");
+        if (parts.length !== 3)
+            return false;
+        const when = new Date(Number(parts[0]), Number(parts[1]) - 1, Number(parts[2]));
+        return when.toDateString() === new Date(root.nowMs).toDateString();
+    }
+
+    // ── Derived views of the selected record ────────────────────────────────
+
+    readonly property var limits: {
+        const entries = root.record && Array.isArray(root.record.limits) ? root.record.limits : [];
+        return entries.filter(entry => entry && Number.isFinite(Number(entry.percent)));
+    }
+
+    readonly property var days: {
+        const entries = root.record && Array.isArray(root.record.recentDays) ? root.record.recentDays : [];
+        // recentDays.messageCount is a token total, despite the legacy name the
+        // collectors inherited.
+        return entries.map(day => ({
+            date: String(day?.date ?? ""),
+            tokens: Number(day?.messageCount) || 0
+        }));
+    }
+
+    readonly property double dayPeak: {
+        let peak = 0;
+        for (const day of root.days)
+            peak = Math.max(peak, day.tokens);
+        return peak;
+    }
+
+    // Top models by total tokens. Five rows is the whole point of the section:
+    // more than that and it stops being a glance.
+    readonly property var models: {
+        const usage = root.record?.modelUsage;
+        if (!usage || typeof usage !== "object")
+            return [];
+        const rows = [];
+        for (const name of Object.keys(usage)) {
+            const bucket = usage[name] || {};
+            const total = (Number(bucket.inputTokens) || 0)
+                + (Number(bucket.outputTokens) || 0)
+                + (Number(bucket.cacheReadInputTokens) || 0)
+                + (Number(bucket.cacheCreationInputTokens) || 0);
+            if (total > 0)
+                rows.push({ name: name, tokens: total });
+        }
+        rows.sort((a, b) => b.tokens - a.tokens);
+        return rows.slice(0, 5);
+    }
+
+    readonly property double modelPeak: root.models.length > 0 ? root.models[0].tokens : 0
+
+    Column {
+        id: body
+        width: parent.width
+        spacing: 8
+
+        // ── Agent tabs ──────────────────────────────────────────────────────
+        //
+        // Only worth drawing when there is a choice to make.
+        Row {
+            width: parent.width
+            spacing: 6
+            visible: root.agents.length > 1
+
+            Repeater {
+                model: root.agents
+
+                delegate: Rectangle {
+                    id: tab
+                    required property var modelData
+
+                    readonly property bool current: root.record && root.record.id === tab.modelData.id
+
+                    width: (body.width - 6 * (root.agents.length - 1)) / root.agents.length
+                    height: 28
+                    radius: 9
+                    border.width: tab.current ? 1 : 0
+                    border.color: Theme.alpha(Theme.accent, 0.3)
+                    color: tab.current
+                        ? Theme.alpha(Theme.accent, 0.14)
+                        : (tabMouse.containsMouse ? Theme.alpha(Theme.fg, Theme.hoverAlpha) : Theme.alpha(Theme.fg, 0.05))
+
+                    Text {
+                        anchors.centerIn: parent
+                        text: tab.modelData.name || tab.modelData.id
+                        color: tab.current ? Theme.fg : Theme.fgDim
+                        elide: Text.ElideRight
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSizeSmall
+                        font.weight: Font.DemiBold
+                    }
+
+                    MouseArea {
+                        id: tabMouse
+                        anchors.fill: parent
+                        hoverEnabled: true
+                        cursorShape: Qt.PointingHandCursor
+                        onClicked: root.selectedId = String(tab.modelData.id ?? "")
+                    }
+                }
+            }
+        }
+
+        // ── Who, and how current ────────────────────────────────────────────
+
+        Item {
+            width: parent.width
+            implicitHeight: Math.max(heroGlyph.implicitHeight, heroName.implicitHeight, tierChip.implicitHeight)
+
+            Text {
+                id: heroGlyph
+                anchors.left: parent.left
+                anchors.verticalCenter: parent.verticalCenter
+                text: "\u{F1719}"                        // md-robot-outline
+                color: Theme.accent
+                font.family: Theme.fontMono
+                font.pixelSize: Theme.fontSizeLarge
+            }
+
+            Text {
+                id: heroName
+                anchors.left: heroGlyph.right
+                anchors.leftMargin: 9
+                anchors.right: tierChip.visible ? tierChip.left : parent.right
+                anchors.rightMargin: 8
+                anchors.verticalCenter: parent.verticalCenter
+                text: root.record?.name ?? "Agent usage"
+                color: Theme.fg
+                elide: Text.ElideRight
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSize
+                font.weight: Font.DemiBold
+            }
+
+            // The plan, when the collector could name one. It is the only thing
+            // from the credential store allowed into a record.
+            Rectangle {
+                id: tierChip
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                visible: String(root.record?.tierLabel ?? "") !== ""
+                implicitWidth: tierText.implicitWidth + 18
+                implicitHeight: tierText.implicitHeight + 6
+                radius: Theme.pillRadius
+                border.width: 1
+                border.color: Theme.alpha(Theme.accent, 0.25)
+                color: Theme.alpha(Theme.accent, 0.1)
+
+                Text {
+                    id: tierText
+                    anchors.centerIn: parent
+                    text: String(root.record?.tierLabel ?? "").toUpperCase()
+                    color: Theme.accent
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Math.max(8, Theme.fontSizeSmall - 2)
+                    font.weight: Font.DemiBold
+                }
+            }
+        }
+
+        Text {
+            width: parent.width
+            text: root.agoText(root.record?.updatedAt)
+            color: Theme.fgMuted
+            elide: Text.ElideRight
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+        }
+
+        // ── An honest word when the numbers are not authoritative ───────────
+
+        Rectangle {
+            width: parent.width
+            visible: String(root.record?.usageStatusText ?? "") !== ""
+            implicitHeight: statusColumn.implicitHeight + 18
+            radius: Theme.cardRadius
+            border.width: 0
+            color: Theme.alpha(Theme.warn, 0.12)
+
+            Column {
+                id: statusColumn
+                anchors.left: parent.left
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                anchors.leftMargin: 10
+                anchors.rightMargin: 10
+                spacing: 3
+
+                Text {
+                    width: parent.width
+                    text: root.record?.usageStatusText ?? ""
+                    color: Theme.warn
+                    wrapMode: Text.WordWrap
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSizeSmall
+                    font.weight: Font.DemiBold
+                }
+
+                Text {
+                    width: parent.width
+                    visible: String(root.record?.authHelpText ?? "") !== ""
+                    text: root.record?.authHelpText ?? ""
+                    color: Theme.fgDim
+                    wrapMode: Text.WordWrap
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSizeSmall
+                }
+            }
+        }
+
+        // ── Limits ──────────────────────────────────────────────────────────
+        //
+        // Model-scoped windows sit in the same list as the flat ones: the
+        // collector settles which window an entry belongs to and titles it, so
+        // "Fable Weekly" reads beside "Weekly (7-day)" rather than under it.
+
+        Repeater {
+            model: root.limits
+
+            delegate: Column {
+                id: limitRow
+                required property var modelData
+
+                width: body.width
+                topPadding: 5
+                spacing: 6
+
+                Item {
+                    width: parent.width
+                    implicitHeight: limitLabel.implicitHeight
+
+                    Text {
+                        id: limitLabel
+                        anchors.left: parent.left
+                        anchors.right: limitValue.left
+                        anchors.rightMargin: 8
+                        text: limitRow.modelData.label ?? "Limit"
+                        color: Theme.fg
+                        elide: Text.ElideRight
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSizeSmall
+                        font.weight: Font.DemiBold
+                    }
+
+                    Text {
+                        id: limitValue
+                        anchors.right: parent.right
+                        anchors.baseline: limitLabel.baseline
+                        text: {
+                            const reset = root.resetText(limitRow.modelData.resetsAt);
+                            const percent = root.percentText(limitRow.modelData.percent);
+                            return reset ? reset + " · " + percent : percent;
+                        }
+                        color: Theme.fgMuted
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSizeSmall
+                        font.features: Theme.tabularFigures
+                    }
+                }
+
+                Rectangle {
+                    width: parent.width
+                    height: 8
+                    radius: 4
+                    border.width: 0
+                    color: Theme.alpha(Theme.fg, 0.08)
+
+                    Rectangle {
+                        width: Math.max(0, Math.min(1, Number(limitRow.modelData.percent) || 0)) * parent.width
+                        height: parent.height
+                        radius: parent.radius
+                        border.width: 0
+                        color: root.meterColor(limitRow.modelData.percent)
+                    }
+                }
+            }
+        }
+
+        Rectangle {
+            width: parent.width
+            visible: root.days.length > 0 || root.models.length > 0
+            height: 1
+            color: Theme.alpha(Theme.fg, 0.08)
+        }
+
+        // ── Tokens, last seven days ─────────────────────────────────────────
+
+        Item {
+            width: parent.width
+            visible: root.dayPeak > 0
+            implicitHeight: dayHeader.implicitHeight + 8 + 56
+
+            Text {
+                id: dayHeader
+                anchors.left: parent.left
+                text: "Tokens, last 7 days"
+                color: Theme.fg
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                font.weight: Font.DemiBold
+            }
+
+            Text {
+                anchors.right: parent.right
+                anchors.baseline: dayHeader.baseline
+                text: "today " + root.tokenText(root.record?.todayTotalTokens ?? 0)
+                color: Theme.fgMuted
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                font.features: Theme.tabularFigures
+            }
+
+            Row {
+                anchors.left: parent.left
+                anchors.right: parent.right
+                anchors.bottom: parent.bottom
+                height: 56
+                spacing: 6
+
+                Repeater {
+                    model: root.days
+
+                    delegate: Column {
+                        id: dayColumn
+                        required property var modelData
+
+                        readonly property bool today: root.isToday(dayColumn.modelData.date)
+
+                        width: (body.width - 6 * 6) / 7
+                        spacing: 4
+
+                        Item {
+                            width: parent.width
+                            height: 56 - 4 - dayLabel.implicitHeight
+
+                            Rectangle {
+                                anchors.bottom: parent.bottom
+                                width: parent.width
+                                height: Math.max(
+                                    dayColumn.modelData.tokens > 0 ? 2 : 0,
+                                    root.dayPeak > 0 ? (dayColumn.modelData.tokens / root.dayPeak) * parent.height : 0)
+                                radius: 4
+                                border.width: 0
+                                color: dayColumn.today ? Theme.accent : Theme.alpha(Theme.accent, 0.35)
+                            }
+                        }
+
+                        Text {
+                            id: dayLabel
+                            width: parent.width
+                            text: root.weekdayText(dayColumn.modelData.date)
+                            color: dayColumn.today ? Theme.fgDim : Theme.fgMuted
+                            horizontalAlignment: Text.AlignHCenter
+                            font.family: Theme.fontFamily
+                            font.pixelSize: Math.max(8, Theme.fontSizeSmall - 2)
+                            font.weight: dayColumn.today ? Font.DemiBold : Font.Normal
+                        }
+                    }
+                }
+            }
+        }
+
+        // ── Where the tokens went ───────────────────────────────────────────
+
+        Text {
+            width: parent.width
+            visible: root.models.length > 0
+            topPadding: 4
+            text: "By model"
+            color: Theme.fg
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+            font.weight: Font.DemiBold
+        }
+
+        Repeater {
+            model: root.models
+
+            delegate: Item {
+                id: modelRow
+                required property var modelData
+
+                width: body.width
+                implicitHeight: 18
+
+                Text {
+                    id: modelName
+                    anchors.left: parent.left
+                    anchors.verticalCenter: parent.verticalCenter
+                    width: 108
+                    text: modelRow.modelData.name
+                    color: Theme.fgDim
+                    elide: Text.ElideRight
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Math.max(9, Theme.fontSizeSmall - 1)
+                }
+
+                Item {
+                    anchors.left: modelName.right
+                    anchors.leftMargin: 10
+                    anchors.right: modelValue.left
+                    anchors.rightMargin: 10
+                    anchors.verticalCenter: parent.verticalCenter
+                    height: 6
+
+                    Rectangle {
+                        width: root.modelPeak > 0
+                            ? Math.max(2, (modelRow.modelData.tokens / root.modelPeak) * parent.width)
+                            : 0
+                        height: parent.height
+                        radius: 3
+                        border.width: 0
+                        color: Theme.alpha(Theme.accentAlt, 0.55)
+                    }
+                }
+
+                Text {
+                    id: modelValue
+                    anchors.right: parent.right
+                    anchors.verticalCenter: parent.verticalCenter
+                    width: 52
+                    text: root.tokenText(modelRow.modelData.tokens)
+                    color: Theme.fgDim
+                    horizontalAlignment: Text.AlignRight
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Math.max(9, Theme.fontSizeSmall - 1)
+                    font.features: Theme.tabularFigures
+                }
+            }
+        }
+
+        // ── Sessions, when that is all there is ─────────────────────────────
+
+        Text {
+            width: parent.width
+            visible: root.dayPeak <= 0 && root.models.length === 0 && root.record !== null
+            text: `Sessions today: ${root.record?.todaySessions ?? 0}`
+            color: Theme.fgDim
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+        }
+
+        Text {
+            width: parent.width
+            visible: root.record === null
+            text: "No collector has anything to report yet."
+            color: Theme.fgDim
+            wrapMode: Text.WordWrap
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+        }
+    }
+}
@@ -0,0 +1,68 @@
+// How much of the busiest agent subscription is gone, beside the other vitals.
+//
+// One number: whichever window across every collected agent is closest to its
+// limit, because that is the one about to interrupt you.
+//
+// Hidden unless asked for AND a collector has real numbers. A bar indicator
+// reading "unknown" is worse than an empty space, and this is off by default:
+// it is a coding-tool readout, not something a general-purpose desktop shows
+// without being asked.
+//
+// The glyph and the number live in their own Row, the same shape VitalsField
+// uses. Anchoring them straight into Pill's layout Row instead made each child
+// centre against a Row whose height those same children determine, and they
+// came out sitting off-centre against the rest of the bar.
+//
+// Clickable, because a readout you cannot ask anything of is furniture. Left
+// click opens the panel behind the number; right click opens the settings that
+// govern it.
+
+import QtQuick
+import qs.config
+import qs.services
+import qs.widgets
+
+Pill {
+    id: root
+
+    visible: Settings.showAgentUsage && AgentUsage.available
+
+    onActivated: panel.visible = !panel.visible
+    onSecondaryActivated: ShellState.openSettings("bar")
+
+    Row {
+        spacing: 4
+
+        Text {
+            anchors.verticalCenter: parent.verticalCenter
+            text: "\u{F1719}"                        // md-robot-outline
+            color: {
+                if (AgentUsage.headline >= 90) return Theme.danger;
+                if (AgentUsage.headline >= 75) return Theme.warn;
+                return Theme.barFgDim;
+            }
+            font.family: Theme.fontMono
+            font.pixelSize: Theme.fontSize
+        }
+
+        Text {
+            anchors.verticalCenter: parent.verticalCenter
+            text: AgentUsage.headline + "%"
+            color: Theme.barFg
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+            font.features: Theme.tabularFigures
+            // Fixed and right-aligned so the bar does not shuffle sideways when
+            // the number gains a digit, exactly as VitalsField does.
+            horizontalAlignment: Text.AlignRight
+            width: 30
+        }
+    }
+
+    // Hangs off this pill the way TrayMenu hangs off a tray icon. A PopupWindow
+    // is not an Item, so it takes no space in Pill's layout Row.
+    AgentUsagePanel {
+        id: panel
+        anchorItem: root
+    }
+}
@@ -16,6 +16,7 @@
 import Quickshell
 import Quickshell.Wayland
 import QtQuick
+import QtQuick.Effects
 import qs.config
 import qs.modules.clipboard
 import qs.modules.focus
@@ -62,11 +63,44 @@ PanelWindow {
        item: barContent
    }

+    // A scrim for wallpapers the bar cannot win against on tone alone. Drawn
+    // behind the content rows, fading out downward so the bar still has no
+    // hard edge of its own — the point is to darken what is under the text,
+    // not to give the bar a surface. Static: a gradient that never changes
+    // costs one paint, and this one has nothing to animate.
+    Rectangle {
+        anchors.fill: parent
+        visible: Settings.barBackdrop
+
+        gradient: Gradient {
+            GradientStop {
+                position: 0.0
+                color: Theme.alpha("#0c0e18", 0.55)
+            }
+            GradientStop {
+                position: 1.0
+                color: "transparent"
+            }
+        }
+    }
+
    Item {
        id: barContent

        anchors.fill: parent

+        // One shadow for the whole bar rather than one per widget: the content
+        // is flattened into a single layer and the halo is drawn under it, so
+        // every glyph and label picks it up and nothing has to opt in. Off by
+        // default — it only earns its layer on a busy wallpaper.
+        layer.enabled: Settings.barTextShadow
+        layer.effect: MultiEffect {
+            shadowEnabled: true
+            shadowColor: "#0a0c14"
+            shadowBlur: 0.6
+            shadowVerticalOffset: 1
+        }
+
        // ── Left ────────────────────────────────────────────────────────────
        Row {
            anchors.left: parent.left
@@ -78,6 +112,10 @@ PanelWindow {
                screen: root.screen
            }

+            AgentUsageWidget {
+                anchors.verticalCenter: parent.verticalCenter
+            }
+
            VitalsWidget {
                anchors.verticalCenter: parent.verticalCenter
            }
@@ -116,6 +154,10 @@ PanelWindow {
                anchors.verticalCenter: parent.verticalCenter
            }

+            WallpaperIndicator {
+                anchors.verticalCenter: parent.verticalCenter
+            }
+
            FocusIndicator {
                anchors.verticalCenter: parent.verticalCenter
            }
@@ -10,7 +10,7 @@ import qs.widgets
 Pill {
    id: root

-    visible: CalendarAgenda.capsuleVisible
+    visible: Settings.showCalendarCountdown && CalendarAgenda.capsuleVisible
    opacity: visible ? 1 : 0
    horizontalPadding: 8
    onActivated: ShellState.openDateMenu("agenda")
@@ -47,7 +47,7 @@ Pill {
    Text {
        anchors.verticalCenter: parent.verticalCenter
        text: CalendarAgenda.capsuleText
-        color: Theme.fg
+        color: Theme.barFg
        font.family: Theme.fontFamily
        font.features: Theme.tabularFigures
        font.pixelSize: Theme.fontSizeSmall
@@ -39,7 +39,7 @@ Pill {
        // figures the whole clock shifts sideways on every digit change.
        font.features: Theme.tabularFigures
        font.pixelSize: Theme.fontSize
-        color: Theme.fg
+        color: Theme.barFg
    }

 }
@@ -29,7 +29,7 @@ Pill {
        return artist ? artist + " — " + title : title;
    }

-    visible: root.player !== null
+    visible: Settings.showMediaWidget && root.player !== null
    horizontalPadding: 8

    onActivated: if (root.player?.canTogglePlaying)
@@ -63,7 +63,7 @@ Pill {
        text: root.label
        font.family: Theme.fontFamily
        font.pixelSize: Theme.fontSize
-        color: Theme.fg
+        color: Theme.barFg

        // Titles are unbounded; the bar is not. Elide rather than let one
        // podcast episode push the tray off the edge.
@@ -77,13 +77,36 @@ Pill {

        color: {
            if (root.wiredDevice)
-                return Theme.fg;
+                return Theme.barFg;
            if (!root.wifiNetwork)
-                return Theme.fgMuted;
-            return Networking.connectivity === NetworkConnectivity.Full ? Theme.fg : Theme.warn;
+                return Theme.barFgMuted;
+            return Networking.connectivity === NetworkConnectivity.Full ? Theme.barFg : Theme.warn;
        }
    }

+    // The active layout, only where there is a choice to indicate: a machine
+    // with one layout knows what its keys say. GNOME shows the same short
+    // code in the same corner, which is the muscle memory this preserves.
+    Text {
+        visible: KeyboardLayout.multiple
+        anchors.verticalCenter: parent.verticalCenter
+        text: KeyboardLayout.shortLabel
+        color: Theme.barFg
+        font.family: Theme.fontFamily
+        font.pixelSize: Theme.fontSizeSmall
+        font.weight: Font.Medium
+        font.letterSpacing: 0.5
+    }
+
+    // A tunnel that is up changes what every connection means, so it earns a
+    // permanent glyph while active -- and its absence is the resting state,
+    // same shape as Bluetooth below.
+    StatusGlyph {
+        visible: Vpn.anyActive
+        glyph: "\u{F0582}"                       // md-vpn
+        color: Theme.accent
+    }
+
    StatusGlyph {
        glyph: {
            if (root.muted || root.volume <= 0)
@@ -94,7 +117,7 @@ Pill {
                return "\u{F0580}";              // md-volume_medium
            return "\u{F057E}";                  // md-volume_high
        }
-        color: root.muted ? Theme.fgMuted : Theme.fg
+        color: root.muted ? Theme.barFgMuted : Theme.barFg
    }

    StatusGlyph {
@@ -102,7 +125,7 @@ Pill {
        // simply absent rather than shown crossed out.
        visible: root.bluetoothOn
        glyph: root.bluetoothConnected ? "\u{F00B1}" : "\u{F00AF}"   // md-bluetooth_connect / md-bluetooth
-        color: root.bluetoothConnected ? Theme.accent : Theme.fg
+        color: root.bluetoothConnected ? Theme.accent : Theme.barFg
    }

    StatusGlyph {
@@ -116,4 +139,50 @@ Pill {
        glyph: "\u{F03F2}"                       // md-cellphone-link
        color: Theme.cyan
    }
+
+    // Battery. Absent entirely on a desktop: `available` is false until a
+    // battery has actually been read, so this is not a zero that looks like a
+    // flat cell. Same shape as the graphics field in VitalsWidget, which gates
+    // on both the preference and the hardware.
+    //
+    // One color for the icon and the number beside it: two different colors
+    // would read as two indicators.
+    readonly property color batteryColor: {
+        if (Battery.critical) return Theme.danger;
+        if (Battery.low) return Theme.warn;
+        if (Battery.charging) return Theme.ok;
+        return Theme.barFg;
+    }
+
+    StatusGlyph {
+        visible: Settings.showBattery && Battery.available
+        glyph: {
+            if (Battery.charging)
+                return "\u{F0084}";              // md-battery_charging
+            const level = Math.round(Battery.percent / 10) * 10;
+            if (level >= 100) return "\u{F0079}";  // md-battery
+            if (level <= 0)   return "\u{F008E}";  // md-battery_outline
+            // md-battery_10 .. md-battery_90 are consecutive from F007A.
+            return String.fromCodePoint(0xF007A + (level / 10) - 1);
+        }
+        color: root.batteryColor
+    }
+
+    // The exact number, for the people who ask the icon to be more specific --
+    // GNOME's "Show Battery Percentage", living under the same gates as the
+    // icon it annotates.
+    Text {
+        visible: Settings.showBattery && Settings.showBatteryPercent && Battery.available
+        anchors.verticalCenter: parent.verticalCenter
+        text: Math.round(Battery.percent) + "%"
+        color: root.batteryColor
+        font.family: Theme.fontFamily
+        font.pixelSize: Theme.fontSizeSmall
+
+        Behavior on color {
+            ColorAnimation {
+                duration: Theme.durFast
+            }
+        }
+    }
 }
@@ -16,7 +16,7 @@ Text {
    font.pixelSize: Theme.fontSizeLarge
    horizontalAlignment: Text.AlignHCenter
    width: 18
-    color: Theme.fg
+    color: Theme.barFg

    Behavior on color {
        ColorAnimation {
@@ -20,7 +20,7 @@ Row {
        text: root.glyph
        font.family: Theme.fontMono
        font.pixelSize: Theme.fontSize
-        color: Theme.fgDim
+        color: Theme.barFgDim
    }

    Text {
@@ -41,7 +41,7 @@ Row {
                return Theme.danger;
            if (root.value >= root.warnAt)
                return Theme.warn;
-            return Theme.fg;
+            return Theme.barFg;
        }

        Behavior on color {
@@ -15,7 +15,12 @@ Pill {

    // Right-click opens the settings that govern this widget. Which readouts
    // appear in the bar, and how often they update.
-    onSecondaryActivated: ShellState.openSettings("appearance")
+    onSecondaryActivated: ShellState.openSettings("bar")
+
+    // Turning off all three readouts should remove the pill, not leave an empty
+    // one behind: an invisible child still occupies its Row, so without this the
+    // padding stays and the bar keeps a gap that reports nothing.
+    visible: Settings.showCpu || Settings.showMemory || (Settings.showGpu && Vitals.gpuAvailable)

    interactive: false

@@ -0,0 +1,40 @@
+// Visible only while a video wallpaper is active: one click pauses or resumes
+// it. Exists because a playing wallpaper has real costs the user may want to
+// stop right now — a remote desktop session, a recording, or just quiet —
+// without opening Settings. Same conditional pattern as ActivityIndicator.
+
+import QtQuick
+import qs.config
+import qs.services
+import qs.widgets
+
+Pill {
+    id: root
+
+    visible: VideoWallpaper.active
+    horizontalPadding: 10
+
+    onActivated: VideoWallpaper.togglePause()
+    onSecondaryActivated: ShellState.openSettings("appearance")
+
+    Accessible.name: VideoWallpaper.paused ? "Resume video wallpaper" : "Pause video wallpaper"
+
+    Text {
+        anchors.verticalCenter: parent.verticalCenter
+        text: VideoWallpaper.paused ? "\u{F040A}" : "\u{F03E4}" // play / pause
+        color: VideoWallpaper.paused ? Theme.barFgDim : Theme.warn
+        font.family: Theme.fontMono
+        font.pixelSize: 13
+    }
+
+    Text {
+        anchors.verticalCenter: parent.verticalCenter
+        text: VideoWallpaper.paused
+            ? (VideoWallpaper.gamePaused ? "Paused for game"
+                : (VideoWallpaper.batteryPaused ? "Paused on battery" : "Paused"))
+            : "Wallpaper"
+        color: Theme.barFgDim
+        font.family: Theme.fontFamily
+        font.pixelSize: Theme.fontSizeSmall
+    }
+}
@@ -14,7 +14,7 @@ Pill {
    onSecondaryActivated: ShellState.openSettings("home")

    interactive: false
-    visible: Weather.available
+    visible: Settings.showWeatherWidget && Weather.available

    Text {
        anchors.verticalCenter: parent.verticalCenter
@@ -29,6 +29,6 @@ Pill {
        text: Math.round(Weather.temperature) + Weather.unitSuffix
        font.family: Theme.fontFamily
        font.pixelSize: Theme.fontSize
-        color: Theme.fg
+        color: Theme.barFg
    }
 }
@@ -132,7 +132,7 @@ Item {
                    color: {
                        if (slot.modelData.urgent)
                            return Theme.urgent;
-                        return slot.isOccupied ? Theme.fg : Theme.alpha(Theme.fg, 0.3);
+                        return slot.isOccupied ? Theme.barFg : Theme.alpha(Theme.barFg, 0.3);
                    }

                    Behavior on color {
@@ -0,0 +1,227 @@
+// Every shortcut, on one keypress.
+//
+// This is a different job from the Shortcuts settings page, which answers "how
+// do I change this" and is worth opening a window for. This answers "what can
+// I press", which is a question you have while your hands are already on the
+// keyboard and which needs answering in under a second. So it is an overlay,
+// it is one key, and it closes on the same key.
+//
+// It reads the live keymap rather than a written-down copy: Keybinds.grouped()
+// comes from `hyprctl binds`, so a shortcut somebody rebound in Settings shows
+// its new chord here without anything being kept in sync. Categories come from
+// hypr/keybinds.lua's manifest -- see Keybinds.categoryManifest.
+//
+// Three columns, balanced by how many shortcuts each category holds. Not a
+// Flow: with about 120 binds across six wildly uneven categories -- Windows has
+// forty, Session has three -- a Flow wraps into as many columns as it likes and
+// the result is unreadable. The columns are computed instead.
+
+import Quickshell
+import Quickshell.Wayland
+import QtQuick
+import qs.config
+import qs.services
+import qs.widgets
+
+PanelWindow {
+    id: root
+
+    readonly property bool open: ShellState.cheatsheetOpen
+
+    readonly property int columnCount: 3
+
+    // Categories dealt into columns, longest first, each going to whichever
+    // column is currently shortest. Sorting first is what stops the fortieth
+    // window bind landing in a column that already has thirty workspace ones.
+    readonly property var columns: {
+        const buckets = [];
+        for (let index = 0; index < root.columnCount; index++)
+            buckets.push({ groups: [], weight: 0 });
+
+        const groups = Array.from(Keybinds.grouped())
+            .sort((a, b) => b.binds.length - a.binds.length);
+
+        for (const group of groups) {
+            let target = buckets[0];
+            for (const bucket of buckets) {
+                if (bucket.weight < target.weight)
+                    target = bucket;
+            }
+            target.groups.push(group);
+            // Two lines of overhead per heading, so a column of many small
+            // categories is not treated as shorter than it looks.
+            target.weight += group.binds.length + 2;
+        }
+        return buckets.map(bucket => bucket.groups);
+    }
+
+    anchors { top: true; bottom: true; left: true; right: true }
+    color: "transparent"
+    exclusiveZone: 0
+    exclusionMode: ExclusionMode.Ignore
+
+    // The `^qs-popover` prefix rule in hypr/rules.lua blurs what is behind
+    // this. The dimming is painted here rather than added to the overlay rule,
+    // the way PolkitPrompt does it, because this is a card on a scrim rather
+    // than a full-screen takeover.
+    WlrLayershell.namespace: "qs-popover-cheatsheet"
+    WlrLayershell.layer: WlrLayer.Overlay
+    WlrLayershell.keyboardFocus: root.open
+        ? WlrKeyboardFocus.Exclusive
+        : WlrKeyboardFocus.None
+
+    // Stays mapped for the length of the close animation, or it vanishes
+    // instantly and only the opening is ever seen.
+    property bool mapped: false
+    visible: root.mapped
+
+    onOpenChanged: {
+        if (root.open) {
+            unmapTimer.stop();
+            root.mapped = true;
+            // The keymap can change while the session runs: a rebind in
+            // Settings, or a compositor reload.
+            Keybinds.refresh();
+        } else {
+            unmapTimer.restart();
+        }
+    }
+
+    Timer {
+        id: unmapTimer
+        interval: Theme.durNormal
+        onTriggered: root.mapped = false
+    }
+
+    Rectangle {
+        anchors.fill: parent
+        color: Theme.alpha(Theme.bgDark, Theme.overlayAlpha)
+        opacity: root.open ? 1 : 0
+        Behavior on opacity { NumberAnimation { duration: Theme.durNormal; easing.type: Easing.OutCubic } }
+
+        // Anywhere outside the card closes it, which is what every other
+        // transient surface on this desktop does.
+        MouseArea {
+            anchors.fill: parent
+            onClicked: ShellState.close()
+        }
+    }
+
+    Rectangle {
+        id: card
+
+        anchors.centerIn: parent
+        width: Math.min(root.width - 120, 1240)
+        // Sized from its content, capped at the screen. Deliberately NOT
+        // computed from a child that fills it: that is a circular binding, and
+        // it produced a card taller than the display with its contents running
+        // off the bottom edge.
+        height: Math.min(root.height - 120, header.height + body.contentHeight + 72)
+
+        radius: Theme.popoverRadius
+        color: Theme.alpha(Theme.bgPopover, Theme.popoverAlpha)
+        border.width: 1
+        border.color: Theme.alpha(Theme.fg, 0.1)
+
+        opacity: root.open ? 1 : 0
+        scale: root.open ? 1 : 0.98
+        Behavior on opacity { NumberAnimation { duration: Theme.durNormal; easing.type: Easing.OutCubic } }
+        Behavior on scale { NumberAnimation { duration: Theme.durNormal; easing.type: Easing.OutCubic } }
+
+        PrismEdge {
+            anchors.top: parent.top
+            anchors.left: parent.left
+            anchors.right: parent.right
+            inset: Theme.popoverRadius
+        }
+
+        // Clicks on the card itself must not fall through to the scrim.
+        MouseArea { anchors.fill: parent }
+
+        Item {
+            id: header
+
+            anchors.top: parent.top
+            anchors.left: parent.left
+            anchors.right: parent.right
+            anchors.margins: 28
+            height: title.implicitHeight
+
+            Text {
+                id: title
+                text: "Keyboard shortcuts"
+                color: Theme.fg
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeLarge
+                font.weight: Font.DemiBold
+            }
+
+            Text {
+                anchors.right: parent.right
+                anchors.verticalCenter: title.verticalCenter
+                text: Keybinds.loaded
+                    ? Keybinds.binds.length + " shortcuts  ·  Esc to close"
+                    : "Reading the keymap…"
+                color: Theme.fgMuted
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+            }
+        }
+
+        // Scrolls only when it has to. On a display tall enough for the whole
+        // keymap this never moves, which is the common case and the one worth
+        // optimising for -- a cheatsheet you have to scroll is a document.
+        Flickable {
+            id: body
+
+            anchors.top: header.bottom
+            anchors.topMargin: 18
+            anchors.left: parent.left
+            anchors.right: parent.right
+            anchors.bottom: parent.bottom
+            anchors.leftMargin: 28
+            anchors.rightMargin: 28
+            anchors.bottomMargin: 28
+
+            contentWidth: width
+            contentHeight: columnRow.implicitHeight
+            clip: true
+            boundsBehavior: Flickable.StopAtBounds
+
+            Row {
+                id: columnRow
+                width: parent.width
+                spacing: 24
+
+                Repeater {
+                    model: root.columns
+
+                    Column {
+                        required property var modelData
+                        width: (columnRow.width - columnRow.spacing * (root.columnCount - 1)) / root.columnCount
+                        spacing: 20
+
+                        Repeater {
+                            model: parent.modelData
+
+                            CheatsheetGroup {
+                                required property var modelData
+                                width: parent.width
+                                name: modelData.name
+                                binds: modelData.binds
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // Escape closes, like every other dialog here. The same chord that opened
+    // it also closes it, which ShellState.toggle handles.
+    Item {
+        anchors.fill: parent
+        focus: true
+        Keys.onEscapePressed: ShellState.close()
+    }
+}
@@ -0,0 +1,66 @@
+// One category of shortcuts, as a column.
+//
+// Deliberately plain: a chord on the left, what it does on the right, and no
+// separators between rows. The cheatsheet is read at a glance while a key is
+// held, so anything that draws the eye away from the two columns is in the way.
+
+import QtQuick
+import qs.config
+
+Column {
+    id: root
+
+    required property string name
+    required property var binds
+
+    spacing: 3
+
+    Text {
+        text: root.name
+        color: Theme.accent
+        font.family: Theme.fontFamily
+        font.pixelSize: Theme.fontSizeSmall
+        font.weight: Font.DemiBold
+        font.capitalization: Font.AllUppercase
+        font.letterSpacing: 0.6
+        bottomPadding: 5
+    }
+
+    Repeater {
+        model: root.binds
+
+        Item {
+            required property var modelData
+
+            width: root.width
+            height: chord.implicitHeight + 5
+
+            // The chord is monospaced and tabular so a column of them lines up
+            // rather than jittering with the width of each key name. This is
+            // the one place in the shell where a monospaced face is correct:
+            // it is showing keys, not prose.
+            Text {
+                id: chord
+                width: 168
+                text: modelData.chord
+                color: Theme.fg
+                font.family: Theme.fontMono
+                font.pixelSize: Theme.fontSizeSmall
+                font.features: Theme.tabularFigures
+                elide: Text.ElideRight
+            }
+
+            Text {
+                anchors.left: chord.right
+                anchors.leftMargin: 10
+                anchors.right: parent.right
+                anchors.verticalCenter: chord.verticalCenter
+                text: modelData.description
+                color: Theme.fgDim
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                elide: Text.ElideRight
+            }
+        }
+    }
+}
@@ -0,0 +1,3 @@
+module qs.modules.cheatsheet
+Cheatsheet 1.0 Cheatsheet.qml
+CheatsheetGroup 1.0 CheatsheetGroup.qml
@@ -9,6 +9,10 @@ import qs.widgets
 Pill {
    id: root

+    // Hiding the button does not retire the feature: Super+V still opens the
+    // history. This only reclaims the space in the bar.
+    visible: Settings.showClipboardButton
+
    implicitWidth: 30
    implicitHeight: 28

@@ -19,6 +23,6 @@ Pill {
        size: 16
        icon: "edit-paste-symbolic"
        iconFallback: "edit-copy-symbolic"
-        tint: ShellState.clipboardOpen ? Theme.accent : Theme.fg
+        tint: ShellState.clipboardOpen ? Theme.accent : Theme.barFg
    }
 }
@@ -94,7 +94,16 @@ PanelWindow {
        return !!ws && ws.toplevels.values.length > 0;
    }

-    readonly property bool wantRevealed: !Settings.dockAutohide || !workspaceOccupied || pointer.hovered
+    // Anything anchored to the dock that the dock would drag off-screen with
+    // it. The pointer leaves the dock the moment it enters an open menu -- the
+    // menu is its own surface -- so without this the dock slides away under
+    // the menu it opened, and the row the hand was reaching for goes with it.
+    // The same is true mid-drag, and while a preview is up.
+    readonly property bool interactionHeld: dockContextMenu.visible
+        || body.dragging
+        || dockPreviews.visible
+
+    readonly property bool wantRevealed: !Settings.dockAutohide || !workspaceOccupied || pointer.hovered || root.interactionHeld

    property bool revealed: true

@@ -120,16 +129,34 @@ PanelWindow {
        onTriggered: root.revealed = false
    }

-    // Other modules (the bar, the capture overlay) read this. It is one
-    // shared flag but there is one Dock per monitor, so only the instance on
-    // the currently-focused monitor is allowed to write it -- otherwise
-    // whichever instance last changed reveal state would stomp the others,
-    // and a reader would see an arbitrary monitor's value. This scopes the
-    // flag to mean "is the dock revealed on the monitor the user is on",
-    // which is what a capture overlay or the bar actually care about.
-    // (A true per-monitor flag would need ShellState.dockRevealed itself to
-    // become keyed by screen, which is out of scope here -- see the report.)
-    readonly property bool isFocusedMonitorInstance: root.monitor === null || root.monitor === Hyprland.focusedMonitor
+    // ShellState.dockRevealed is one shared flag and there is one Dock per
+    // monitor, so exactly one instance may write it -- otherwise whichever
+    // instance last changed reveal state stomps the others and a reader gets an
+    // arbitrary monitor's answer. Scoped this way the flag means "is the dock
+    // revealed on the monitor the user is on", which is the only question a
+    // reader outside the dock can sensibly ask of it. (A genuinely per-monitor
+    // answer would need the property itself keyed by screen.)
+    //
+    // Two things disqualify an instance. One is not being on the focused
+    // monitor, which is the whole point. The other is not being on screen at
+    // all: a Dock whose screen is not in `dockScreens` is invisible, and an
+    // invisible dock reporting itself as revealed is a lie a reader acts on. An
+    // instance whose monitor could not be resolved -- created standalone, or
+    // asked before Hyprland has reported the screen -- knows nothing about
+    // which monitor the user is on, so it writes only when there is no focused
+    // monitor to be wrong about rather than stomping the instance that knows.
+    //
+    // Nothing reads the flag today: the bar and the capture overlay it was
+    // written for both stopped. It is written correctly rather than left
+    // half-wrong, and when ShellState is next opened the property, this
+    // arbitration and _syncShellState should go together.
+    readonly property bool isFocusedMonitorInstance: {
+        if (!root.onThisScreen)
+            return false;
+        if (root.monitor !== null)
+            return root.monitor === Hyprland.focusedMonitor;
+        return Hyprland.focusedMonitor === null;
+    }

    onRevealedChanged: root._syncShellState()
    onIsFocusedMonitorInstanceChanged: root._syncShellState()
@@ -174,6 +201,33 @@ PanelWindow {
        Item {
            id: maskItem

+            // Where the body comes to rest once the slide finishes, mirroring
+            // DockBody's own x/y bindings in their revealed case.
+            //
+            // The revealed region is built from these rather than from the
+            // body's live position. The body slides in over a couple of hundred
+            // milliseconds, and a region that follows it in is a region that is
+            // a few pixels tall on the frame the dock is summoned -- the exact
+            // frame the pointer that summoned it needs to be inside, and the
+            // exact frame it drops the hover and sends the dock back. Following
+            // the animation also means an input-region commit to the compositor
+            // on every one of those frames, for a rectangle that is only right
+            // on the last of them.
+            //
+            // Clamped rather than assigned outright so the mask still tracks
+            // the body if anything else ever moves it: the reveal only ever
+            // approaches these values from outside the screen edge.
+            readonly property real settledX: {
+                if (!root.vertical)
+                    return body.x;
+                return root.position === "left"
+                    ? Math.max(body.x, root.tooltipSpace)
+                    : Math.min(body.x, surface.width - body.width - root.tooltipSpace);
+            }
+            readonly property real settledY: root.vertical
+                ? body.y
+                : Math.min(body.y, root.tooltipSpace)
+
            x: {
                if (!root.revealed)
                    return root.position === "right" ? surface.width - root.revealStripHeight : 0;
@@ -185,35 +239,41 @@ PanelWindow {
                // to its own edge, which is x 0 on the left and the body on
                // the right.
                if (!root.vertical)
-                    return body.x;
-                return root.position === "right" ? body.x : 0;
+                    return maskItem.settledX;
+                return root.position === "right" ? maskItem.settledX : 0;
            }
            y: {
                if (!root.revealed)
                    return root.vertical ? 0 : surface.height - root.revealStripHeight;
-                return body.y;
+                return maskItem.settledY;
            }
            width: {
                if (!root.revealed)
                    return root.vertical ? root.revealStripHeight : surface.width;
                return root.vertical
-                    ? (root.position === "right" ? surface.width - body.x : body.x + body.width)
+                    ? (root.position === "right"
+                        ? surface.width - maskItem.settledX
+                        : maskItem.settledX + body.width)
                    : body.width;
            }
            height: {
                if (!root.revealed)
                    return root.vertical ? surface.height : root.revealStripHeight;
-                return root.vertical ? body.height : surface.height - body.y;
+                return root.vertical ? body.height : surface.height - maskItem.settledY;
            }
        }

        DockBody {
            id: body

-            onContextMenuRequested: (anchorItem, entry) => {
+            onContextMenuRequested: (anchorItem, app) => {
+                // The whole app object, not its desktop entry: the menu lists
+                // the app's own windows and offers to pin or unpin it, and
+                // neither fact survives being narrowed to an entry.
+                body.dismissPreview();
                dockContextMenu.anchorItem = anchorItem;
-                dockContextMenu.entry = entry;
-                dockContextMenu.visible = true;
+                dockContextMenu.app = app;
+                dockContextMenu.requested = true;
            }

            vertical: root.vertical
@@ -270,4 +330,50 @@ PanelWindow {
    DockContextMenu {
        id: dockContextMenu
    }
+
+    // The safety net for a latched interaction flag.
+    //
+    // Every term of `interactionHeld` is cleared by an event that can go
+    // missing: a drag by its release, which a stolen grab eats; a preview by
+    // the pointer leaving, which a destroyed anchor never reports; a menu by a
+    // row being chosen, which a menu whose anchor died is never offered. Any
+    // one of them left set holds the dock revealed with the pointer nowhere
+    // near it, and there is no gesture that gets it back -- the flag is stuck,
+    // so the dock is out until the shell restarts.
+    //
+    // Eight seconds of held-but-untouched is not a gesture. The pointer being
+    // on the previews or on the menu counts as touched, because both are their
+    // own surfaces and leaving the dock is how you reach them.
+    Timer {
+        id: interactionWatchdog
+
+        interval: 8000
+        running: root.interactionHeld && !pointer.hovered
+            && !dockPreviews.hovered && !dockContextMenu.hovered
+
+        onTriggered: {
+            body.cancelDrag();
+            body.dismissPreview();
+            dockContextMenu.requested = false;
+        }
+    }
+
+    // Its own surface rather than something drawn inside the dock: the dock's
+    // input mask is a thin strip when hidden and the bar's own rectangle when
+    // shown, and widening it to cover a preview would hand the dock every
+    // click in the empty space above it.
+    DockPreviews {
+        id: dockPreviews
+
+        anchorItem: body.previewAnchor
+        app: body.previewApp
+        position: root.position
+
+        // The pointer crossing from the icon to the previews leaves the dock
+        // entirely -- these are separate surfaces -- so the previews report
+        // their own hover back, and DockBody's grace timer uses it to tell
+        // "reaching for a preview" from "moved away".
+        onHoveredChanged: body.previewHovered = dockPreviews.hovered
+        onDismissed: body.dismissPreview()
+    }
 }
@@ -16,7 +16,12 @@ Rectangle {
    // ── Model ───────────────────────────────────────────────────────────────
    // One pass over the live toplevel list produces the whole dock: pinned
    // apps first in Settings order, then anything else that is running.
-    // Entries are plain JS objects: { entry, windows, appId }.
+    // Entries are plain JS objects: { entry, windows, appId, pinned }.
+    //
+    // `pinned` is carried rather than inferred later. Two things need it — the
+    // context menu, which cannot otherwise tell "Pin" from "Unpin", and the
+    // drag, which must refuse to reorder an icon that is only there because the
+    // app happens to be running.
    readonly property var items: {
        // DesktopEntries is scanned asynchronously at startup, and byId() is a
        // plain method call that creates no binding dependency. Reading the
@@ -63,7 +68,8 @@ Rectangle {
            out.push({
                entry: entry,
                windows: windows,
-                appId: pinned[i]
+                appId: pinned[i],
+                pinned: true
            });
        }

@@ -74,7 +80,8 @@ Rectangle {
            out.push({
                entry: DesktopEntries.heuristicLookup(appId),
                windows: groups[appId],
-                appId: appId
+                appId: appId,
+                pinned: false
            });
        }

@@ -116,7 +123,11 @@ Rectangle {

    // The item the tooltip is currently describing, or null.
    property Item hoveredItem: null
-    signal contextMenuRequested(Item anchorItem, var entry)
+
+    // The whole app object travels, not just its desktop entry: the menu has to
+    // be able to list the app's windows and tell a pin from something that is
+    // merely running, and neither fact survives being narrowed to an entry.
+    signal contextMenuRequested(Item anchorItem, var app)

    // Set by the Dock. A side dock runs the same strip down the screen instead
    // of across it.
@@ -126,6 +137,190 @@ Rectangle {
    // it never opens off-screen.
    property bool leftSide: true

+    // ── Reordering ──────────────────────────────────────────────────────────
+    // Dragging an icon along the dock moves its pin. Nothing is written while
+    // the gesture runs: the dragged icon is translated under the pointer, the
+    // icons it passes are translated the other way by exactly one slot, and the
+    // spliced list is committed once on release. Committing per slot crossed
+    // would rewrite settings.json a dozen times for one gesture, and every
+    // rewrite re-evaluates `items` underneath the drag.
+    //
+    // Translation rather than assigned x/y because a Grid owns its children's
+    // positions; a transform is a purely visual offset the positioner ignores.
+    property int dragIndex: -1
+    property string dragId: ""
+    property real dragTravel: 0
+
+    readonly property bool dragging: root.dragIndex >= 0
+
+    // One cell plus the gap after it: the distance the strip moves things by.
+    // Reported by the item that started the drag rather than recomputed here --
+    // a DockItem is taller than it is wide, so a slot down a side dock is not
+    // the same distance as a slot across a bottom one. The initial value only
+    // has to be non-zero; the first drag replaces it with the measured pitch.
+    property real dragStep: Theme.dockIconSize + Theme.dockGap
+
+    // How many pins are on the dock. Resolved pins are always the leading run
+    // of `items`, so this doubles as the last index a drag may land on.
+    readonly property int pinnedCount: {
+        let count = 0;
+        for (let i = 0; i < root.items.length; i++) {
+            if (!root.items[i].pinned)
+                break;
+            count++;
+        }
+        return count;
+    }
+
+    readonly property int dropIndex: {
+        if (root.dragIndex < 0)
+            return -1;
+        const slots = Math.round(root.dragTravel / root.dragStep);
+        return Math.max(0, Math.min(root.pinnedCount - 1, root.dragIndex + slots));
+    }
+
+    // Where item `index` sits while a drag is in flight, relative to the slot
+    // the Grid put it in.
+    function dragShiftFor(index: int): real {
+        if (root.dragIndex < 0)
+            return 0;
+        if (index === root.dragIndex)
+            return root.dragTravel;
+        if (root.dropIndex > root.dragIndex && index > root.dragIndex && index <= root.dropIndex)
+            return -root.dragStep;
+        if (root.dropIndex < root.dragIndex && index >= root.dropIndex && index < root.dragIndex)
+            return root.dragStep;
+        return 0;
+    }
+
+    function beginDrag(index: int, pitch: real): void {
+        if (index < 0 || index >= root.pinnedCount)
+            return;
+        // A preview anchored to an icon that is about to move under the pointer
+        // is a surface pointing at nothing.
+        root.dismissPreview();
+        if (pitch > 0)
+            root.dragStep = pitch;
+        root.dragIndex = index;
+        root.dragId = root.items[index].appId;
+        root.dragTravel = 0;
+    }
+
+    function moveDrag(travel: real): void {
+        if (root.dragIndex < 0)
+            return;
+        root.dragTravel = travel;
+    }
+
+    // Resolved by pin id rather than by index. `items` drops a pin that no
+    // longer resolves, so an index into the dock is not an index into the
+    // stored list, and a window opening mid-drag can shift both.
+    function endDrag(): void {
+        const target = root.dropIndex;
+        const from = root.dragId;
+        const to = target >= 0 && target < root.items.length ? root.items[target].appId : "";
+        root.dragIndex = -1;
+        root.dragId = "";
+        root.dragTravel = 0;
+
+        if (!from || !to || from === to)
+            return;
+
+        const stored = Settings.dockPinned.slice();
+        const fromAt = stored.indexOf(from);
+        const toAt = stored.indexOf(to);
+        if (fromAt < 0 || toAt < 0)
+            return;
+        stored.splice(toAt, 0, stored.splice(fromAt, 1)[0]);
+        DesktopPreferences.set("dockPinned", stored);
+    }
+
+    function cancelDrag(): void {
+        root.dragIndex = -1;
+        root.dragId = "";
+        root.dragTravel = 0;
+    }
+
+    // ── Window previews ─────────────────────────────────────────────────────
+    // Hovering an icon long enough shows its windows. The dwell exists so that
+    // sweeping the pointer across the dock on the way somewhere else never
+    // opens anything, and the grace on the way out exists because the previews
+    // are their own surface: leaving the icon to reach them would otherwise
+    // close the thing being reached for.
+    property Item previewAnchor: null
+
+    // Looked up in the live model rather than snapshotted when the dwell fires.
+    // `items` is rebuilt into fresh objects whenever any window opens or
+    // closes, so a snapshot keeps the window list the app had when the pointer
+    // stopped moving: a window closed while its preview is up stays in the
+    // strip, and its ScreencopyView goes on holding a handle to a surface that
+    // no longer exists. Reading it back out of `items` means the strip empties
+    // itself, and an app whose last window closed drops the preview entirely.
+    readonly property var previewApp: {
+        const anchor = root.previewAnchor;
+        if (!anchor || !anchor.app)
+            return null;
+        const id = anchor.app.appId;
+        for (let i = 0; i < root.items.length; i++) {
+            if (root.items[i].appId === id)
+                return root.items[i];
+        }
+        return null;
+    }
+
+    // Written by the Dock from the preview popup's own hover.
+    property bool previewHovered: false
+
+    onHoveredItemChanged: root.reconsiderPreview()
+    onPreviewHoveredChanged: root.reconsiderPreview()
+    // A window opening or closing changes what the strip should be showing --
+    // including, when it was the last one, whether there should be a strip.
+    onItemsChanged: root.reconsiderPreview()
+
+    function reconsiderPreview(): void {
+        const item = root.hoveredItem;
+        const eligible = item && item.app && item.app.windows && item.app.windows.length > 0;
+
+        if (eligible && item !== root.previewAnchor) {
+            previewGrace.stop();
+            previewDwell.restart();
+            return;
+        }
+
+        previewDwell.stop();
+        if (root.previewAnchor && !eligible && !root.previewHovered)
+            previewGrace.restart();
+        else if (eligible || root.previewHovered)
+            previewGrace.stop();
+    }
+
+    function dismissPreview(): void {
+        previewDwell.stop();
+        previewGrace.stop();
+        root.previewAnchor = null;
+        root.previewHovered = false;
+    }
+
+    Timer {
+        id: previewDwell
+        interval: 400
+        onTriggered: {
+            const item = root.hoveredItem;
+            if (!item || !item.app || !item.app.windows || item.app.windows.length === 0)
+                return;
+            root.previewAnchor = item;
+        }
+    }
+
+    Timer {
+        id: previewGrace
+        interval: 220
+        onTriggered: {
+            if (!root.previewHovered)
+                root.dismissPreview();
+        }
+    }
+
    // Explicit rather than left to Grid's wrapping. This is always one line, so
    // saying how many cells it holds is both simpler to read and immune to
    // Grid's default column count quietly wrapping a long dock.
@@ -162,16 +357,50 @@ Rectangle {
        }

        Repeater {
-            model: root.items
+            // `items` is a fresh array of fresh objects on every change -- a
+            // window opening or closing anywhere rebuilds all of it. Handing
+            // that straight to Repeater resets the model and rebuilds every
+            // delegate, which throws away hover state, restarts the grow
+            // animation on icons nothing happened to, and would drop the
+            // delegate out from under a drag in progress. ScriptModel keyed on
+            // appId turns the same rebuild into "these rows changed", so an
+            // icon whose window count went up keeps its delegate.
+            model: ScriptModel {
+                values: root.items
+                objectProp: "appId"
+                comparisonMode: ObjectComparison.Structure
+            }

            DockItem {
                id: dockItem
                required property var modelData
+                required property int index
+
                app: modelData
+                vertical: root.vertical
+
+                // Only a pin can be reordered. An icon that is on the dock
+                // because its app happens to be running has no place in the
+                // stored list to move to.
+                draggable: modelData.pinned === true
+                dragShift: root.dragShiftFor(dockItem.index)
+                dragging: root.dragIndex === dockItem.index
+
                onEntered: root.hoveredItem = dockItem
                onExited: if (root.hoveredItem === dockItem)
                    root.hoveredItem = null
-                onContextMenuRequested: root.contextMenuRequested(dockItem, dockItem.entry)
+                onContextMenuRequested: root.contextMenuRequested(dockItem, dockItem.app)
+                onDragStarted: pitch => root.beginDrag(dockItem.index, pitch)
+                onDragMoved: travel => root.moveDrag(travel)
+                onDragEnded: root.endDrag()
+                onDragCancelled: root.cancelDrag()
+
+                // Keying the model keeps a delegate alive through a rebuild,
+                // but not through the app's last window closing while it is
+                // being dragged: that row is gone, and the release it owed is
+                // gone with it. Without this the dock keeps dragIndex forever,
+                // which reads as a dock that will not hide again.
+                Component.onDestruction: if (root.dragIndex === dockItem.index) root.cancelDrag()
            }
        }
    }
@@ -186,7 +415,9 @@ Rectangle {
        readonly property string text: root.hoveredItem ? root.hoveredItem.label : ""

        visible: opacity > 0
-        opacity: root.hoveredItem && tipLabel.text ? 1 : 0
+        // Yields to the window previews, which name the same app and more
+        // besides -- both at once is the same label twice.
+        opacity: root.hoveredItem && tipLabel.text && root.previewAnchor !== root.hoveredItem ? 1 : 0

        Behavior on opacity {
            NumberAnimation {
@@ -1,7 +1,9 @@
-// The dock's app menu. Desktop-entry actions stay first; the shell-owned
-// configuration route is deliberately last so it never displaces app actions.
+// The dock's app menu: its open windows, then what the .desktop file offers,
+// then what the dock itself can do with the app. The shell-owned configuration
+// route is deliberately last so it never displaces an app action.

 import Quickshell
+import Quickshell.Hyprland
 import QtQuick
 import qs.config
 import qs.modules.bar
@@ -12,19 +14,99 @@ PopupWindow {
    id: root

    property Item anchorItem: null
-    property var entry: null
+
+    // The whole dock entry: { entry, windows, appId, pinned }. Narrowing this
+    // to a desktop entry on the way in is what used to stop the menu offering
+    // anything about the app's actual windows, or knowing whether it is pinned.
+    property var app: null
+
+    readonly property DesktopEntry entry: root.app && root.app.entry ? root.app.entry : null
+    readonly property var windows: root.app && root.app.windows ? root.app.windows : []
+    readonly property bool pinned: root.app ? root.app.pinned === true : false

    anchor.item: root.anchorItem
    anchor.edges: Edges.Top | Edges.Left
    anchor.gravity: Edges.Top | Edges.Right
    anchor.margins.bottom: 8

-    implicitWidth: Math.max(menu.implicitWidth + Theme.popoverPadding * 2, 240)
+    implicitWidth: Math.min(360, Math.max(menu.implicitWidth + Theme.popoverPadding * 2, 240))
    implicitHeight: menu.implicitHeight + Theme.popoverPadding * 2
    color: "transparent"
-    visible: false
    grabFocus: true

+    // Whether the dock has asked for the menu. Visibility is that AND a live
+    // anchor, rather than the request alone: the dock icon a menu is anchored
+    // to is a delegate, and a delegate dies when its app's last window closes.
+    // An anchored PopupWindow whose anchor has gone stays mapped with a null
+    // anchor -- a menu hanging over the desktop, attached to nothing, holding
+    // the dock revealed behind it.
+    property bool requested: false
+    visible: root.requested && root.anchorItem !== null
+
+    onAnchorItemChanged: if (root.anchorItem === null) root.requested = false
+
+    // Read by the Dock's interaction watchdog. A menu with the pointer on it is
+    // a menu being read, not a stuck flag -- and the pointer being here means
+    // it is not on the dock, which is the only other thing the dock can see.
+    readonly property bool hovered: menuPointer.hovered
+
+    // Long window titles are the one thing here that can be arbitrarily wide,
+    // and a menu as wide as a browser tab's title is not a menu.
+    function shortTitle(toplevel: var): string {
+        const title = String(toplevel?.title ?? "").trim();
+        if (!title)
+            return root.app && root.app.appId ? root.app.appId : "Untitled window";
+        return title.length > 42 ? title.slice(0, 41) + "…" : title;
+    }
+
+    function addressOf(toplevel: var): string {
+        const raw = String(toplevel?.address ?? "");
+        if (!raw)
+            return "";
+        return raw.startsWith("0x") ? raw : "0x" + raw;
+    }
+
+    function focusToplevel(toplevel: var): void {
+        if (!toplevel)
+            return;
+        if (toplevel.workspace)
+            toplevel.workspace.activate();
+
+        const address = root.addressOf(toplevel);
+        if (address)
+            Hyprland.dispatch(`hl.dsp.focus({ window = "address:${address}" })`);
+        else if (toplevel.wayland)
+            toplevel.wayland.activate();
+    }
+
+    // Every window, not the focused one: "Quit" on a dock icon means the app,
+    // which is what the icon stands for.
+    function quit(): void {
+        for (const toplevel of root.windows) {
+            const address = root.addressOf(toplevel);
+            if (address)
+                Hyprland.dispatch(`hl.dsp.window.close({ window = "address:${address}" })`);
+        }
+    }
+
+    // Always the whole array through DesktopPreferences, which is the only
+    // thing the Settings page and the dock agree on.
+    function pin(): void {
+        if (!root.entry)
+            return;
+        const stored = Settings.dockPinned;
+        if (stored.indexOf(root.entry.id) >= 0)
+            return;
+        DesktopPreferences.set("dockPinned", stored.concat([root.entry.id]));
+    }
+
+    function unpin(): void {
+        const id = root.app && root.app.appId ? root.app.appId : "";
+        if (!id)
+            return;
+        DesktopPreferences.set("dockPinned", Settings.dockPinned.filter(other => other !== id));
+    }
+
    Rectangle {
        anchors.fill: parent
        radius: Theme.popoverRadius
@@ -32,6 +114,10 @@ PopupWindow {
        border.width: 1
        border.color: Theme.alpha(Theme.fg, 0.08)

+        HoverHandler {
+            id: menuPointer
+        }
+
        PrismEdge {
            anchors.top: parent.top
            anchors.topMargin: 1
@@ -46,6 +132,33 @@ PopupWindow {
            anchors.margins: Theme.popoverPadding
            spacing: 2

+            // ── The app's own windows ───────────────────────────────────────
+            Repeater {
+                id: openWindows
+                model: root.windows
+
+                delegate: TrayMenuRow {
+                    required property var modelData
+
+                    width: parent.width
+                    label: root.shortTitle(modelData)
+                    onActivated: {
+                        root.focusToplevel(modelData);
+                        root.requested = false;
+                    }
+                }
+            }
+
+            Rectangle {
+                width: parent.width
+                height: 1
+                anchors.margins: 3
+                visible: openWindows.count > 0
+                border.width: 0
+                color: Theme.alpha(Theme.fg, 0.1)
+            }
+
+            // ── What the .desktop file offers ───────────────────────────────
            Repeater {
                id: applicationActions
                model: root.entry ? root.entry.actions : []
@@ -57,7 +170,7 @@ PopupWindow {
                    label: modelData.name
                    onActivated: {
                        modelData.execute();
-                        root.visible = false;
+                        root.requested = false;
                    }
                }
            }
@@ -71,12 +184,60 @@ PopupWindow {
                color: Theme.alpha(Theme.fg, 0.1)
            }

+            // ── What the dock can do with it ────────────────────────────────
+            TrayMenuRow {
+                width: parent.width
+                label: "New window"
+                // A running application with no desktop entry cannot be
+                // launched again -- there is nothing that says how.
+                rowEnabled: root.entry !== null
+                onActivated: {
+                    if (root.entry)
+                        root.entry.execute();
+                    root.requested = false;
+                }
+            }
+
+            TrayMenuRow {
+                width: parent.width
+                label: root.pinned ? "Unpin from dock" : "Pin to dock"
+                // Unpinning needs only the id the pin was stored under;
+                // pinning needs an entry to name, and an app whose id resolves
+                // to nothing would be pinned as a hole.
+                rowEnabled: root.pinned || root.entry !== null
+                onActivated: {
+                    if (root.pinned)
+                        root.unpin();
+                    else
+                        root.pin();
+                    root.requested = false;
+                }
+            }
+
+            TrayMenuRow {
+                width: parent.width
+                label: root.windows.length > 1 ? "Quit all windows" : "Quit"
+                rowEnabled: root.windows.length > 0
+                onActivated: {
+                    root.quit();
+                    root.requested = false;
+                }
+            }
+
+            Rectangle {
+                width: parent.width
+                height: 1
+                anchors.margins: 3
+                border.width: 0
+                color: Theme.alpha(Theme.fg, 0.1)
+            }
+
            TrayMenuRow {
                width: parent.width
                label: "Dock settings"
                onActivated: {
-                    ShellState.openSettings("desktop");
-                    root.visible = false;
+                    ShellState.openSettings("dock");
+                    root.requested = false;
                }
            }
        }
@@ -11,8 +11,8 @@ import qs.config
 Item {
    id: root

-    // { entry: DesktopEntry|null, windows: [HyprlandToplevel], appId: string }
-    // Built by DockBody so this file stays presentational.
+    // { entry: DesktopEntry|null, windows: [HyprlandToplevel], appId: string,
+    //   pinned: bool }. Built by DockBody so this file stays presentational.
    required property var app

    readonly property DesktopEntry entry: app && app.entry ? app.entry : null
@@ -21,16 +21,49 @@ Item {
    readonly property bool running: windows.length > 0
    readonly property bool hovered: mouse.containsMouse

+    // Set by DockBody. Which way the dock runs decides which axis a drag reads.
+    property bool vertical: false
+
+    // Reordering, driven from DockBody: whether this icon may be dragged at
+    // all, how far it is currently displaced, and whether it is the one being
+    // dragged rather than one being pushed aside.
+    property bool draggable: false
+    property real dragShift: 0
+    property bool dragging: false
+
    // Emitted so DockBody can drive the single shared tooltip.
    signal entered
    signal exited
    signal contextMenuRequested

+    // The drag, reported as travel along the dock's own axis from where the
+    // press landed. DockBody owns what that means.
+    //
+    // The start also carries the pitch -- one cell plus the gap after it --
+    // because the cell size is this file's business: an item is taller than it
+    // is wide (the running dots sit under the icon), so a slot down a side dock
+    // is further than a slot across a bottom one. Measuring it here rather than
+    // recomputing it in DockBody keeps one copy of that arithmetic.
+    signal dragStarted(real pitch)
+    signal dragMoved(real travel)
+    signal dragEnded
+    signal dragCancelled
+
    // The icon may grow past the cell on hover; the cell itself stays a fixed
    // size so the row doesn't reflow.
    implicitWidth: Theme.dockIconSize
    implicitHeight: Theme.dockIconSize + dots.height + 4

+    // Above the icons it is passing.
+    z: root.dragging ? 2 : 0
+
+    // A transform, not an x/y binding: the Grid owns those, and assigning them
+    // in a delegate fights the positioner rather than moving the icon.
+    transform: Translate {
+        x: root.vertical ? 0 : root.dragShift
+        y: root.vertical ? root.dragShift : 0
+    }
+
    // Desktop entries usually carry a freedesktop icon *name*, but some ship an
    // absolute path. iconPath() only understands names, so branch on it. The
    // `true` argument makes a missing icon return "" instead of a placeholder
@@ -118,10 +151,94 @@ Item {
        hoverEnabled: true
        acceptedButtons: Qt.LeftButton | Qt.MiddleButton | Qt.RightButton

+        // Where the press landed, and whether it has travelled far enough to
+        // stop being a click. The threshold is the whole reason a drag can
+        // share this MouseArea with the launch click: a hand that means to
+        // click never moves eight pixels while the button is down.
+        readonly property int dragThreshold: 8
+        property real pressX: 0
+        property real pressY: 0
+        property bool dragActive: false
+        property bool dragConsumed: false
+
+        // A wheel notch is 120 units, but a touchpad sends far smaller ones and
+        // a free-spinning wheel sends larger. Accumulating and spending whole
+        // notches is what makes both feel the same -- reacting to every event
+        // would make a touchpad flick blur through every window an app owns.
+        property int wheelTravel: 0
+
        onEntered: root.entered()
        onExited: root.exited()

+        onWheel: event => {
+            if (!root.running) {
+                mouse.wheelTravel = 0;
+                return;
+            }
+            mouse.wheelTravel += event.angleDelta.y;
+            while (mouse.wheelTravel >= 120) {
+                mouse.wheelTravel -= 120;
+                root.focusBy(-1);
+            }
+            while (mouse.wheelTravel <= -120) {
+                mouse.wheelTravel += 120;
+                root.focusBy(1);
+            }
+        }
+
+        onPressed: mev => {
+            // A press arriving while a drag is still marked active means the
+            // last one never got its release -- a grab stolen by a surface that
+            // opened over the dock, most often. Clearing the flag alone would
+            // leave DockBody still holding a dragIndex, and with it the
+            // interaction hold that keeps the dock revealed forever; the drag
+            // has to be cancelled through the same path a stolen grab uses.
+            if (mouse.dragActive) {
+                mouse.dragActive = false;
+                mouse.dragConsumed = false;
+                root.dragCancelled();
+            }
+            mouse.pressX = mev.x;
+            mouse.pressY = mev.y;
+            mouse.dragActive = false;
+            mouse.dragConsumed = false;
+        }
+
+        onPositionChanged: mev => {
+            if (!root.draggable || !mouse.pressedButtons)
+                return;
+            const travel = root.vertical ? mev.y - mouse.pressY : mev.x - mouse.pressX;
+            if (!mouse.dragActive) {
+                if (Math.abs(travel) < mouse.dragThreshold)
+                    return;
+                mouse.dragActive = true;
+                mouse.dragConsumed = true;
+                root.dragStarted((root.vertical ? root.height : root.width) + Theme.dockGap);
+            }
+            root.dragMoved(travel);
+        }
+
+        onReleased: {
+            if (!mouse.dragActive)
+                return;
+            mouse.dragActive = false;
+            root.dragEnded();
+        }
+
+        onCanceled: {
+            if (!mouse.dragActive)
+                return;
+            mouse.dragActive = false;
+            mouse.dragConsumed = false;
+            root.dragCancelled();
+        }
+
        onClicked: mev => {
+            // A gesture that reordered the dock is not also a launch.
+            if (mouse.dragConsumed) {
+                mouse.dragConsumed = false;
+                return;
+            }
            // Middle click always starts a new instance, as in GNOME.
            if (mev.button === Qt.MiddleButton) {
                root.launch();
@@ -132,7 +249,7 @@ Item {
                return;
            }
            if (root.running)
-                root.focusNext();
+                root.focusBy(1);
            else
                root.launch();
        }
@@ -143,19 +260,26 @@ Item {
            root.entry.execute();
    }

-    // Clicking a running app cycles through its windows, matching GNOME's dash.
-    function focusNext(): void {
+    // Stepping through an app's windows: clicking a running app takes one step
+    // forward, matching GNOME's dash, and the wheel takes one in either
+    // direction. With nothing of this app focused, any step lands on its first
+    // window rather than counting from a window the user is not looking at.
+    function focusBy(delta: int): void {
        const wins = root.windows;
        if (wins.length === 0)
            return;

-        let next = wins[0];
+        let current = -1;
        for (let i = 0; i < wins.length; i++) {
            if (wins[i].activated) {
-                next = wins[(i + 1) % wins.length];
+                current = i;
                break;
            }
        }
+
+        const next = current < 0
+            ? wins[0]
+            : wins[((current + delta) % wins.length + wins.length) % wins.length];
        if (!next)
            return;

@@ -0,0 +1,171 @@
+// "Add application to dock", reachable without opening Settings.
+//
+// The Settings page is the place to curate the whole dock -- reorder it, unpin
+// things, change how it hides. Adding one application is a single decision made
+// while looking at the dock, and routing it through a settings window means
+// finding the page, then the card, then the box. This is that box, on its own.
+//
+// It embeds the same DockAppPicker the Dock page uses rather than growing a
+// second search: the exclusion of already-pinned applications, the icon lookup
+// and the "nothing until you type" behavior are all already there, and two
+// copies of them would drift.
+
+import Quickshell
+import Quickshell.Wayland
+import QtQuick
+import qs.config
+import qs.services
+import qs.modules.settings
+import qs.widgets
+
+PanelWindow {
+    id: root
+
+    readonly property bool open: ShellState.dockPickerOpen
+
+    // The one place a pin is added from outside the Settings page. Returns
+    // false for an id nothing installs, so the IPC caller hears about a typo
+    // instead of the dock quietly gaining a hole -- DockBody drops a pin it
+    // cannot resolve, so a bad id is invisible at runtime.
+    function pin(id: string): bool {
+        const wanted = String(id ?? "").trim();
+        if (!wanted || !DesktopEntries.byId(wanted))
+            return false;
+        const stored = Settings.dockPinned;
+        if (stored.indexOf(wanted) >= 0)
+            return true;
+        DesktopPreferences.set("dockPinned", stored.concat([wanted]));
+        return true;
+    }
+
+    anchors { top: true; bottom: true; left: true; right: true }
+    color: "transparent"
+    exclusiveZone: 0
+    exclusionMode: ExclusionMode.Ignore
+
+    // Blurred by the `^qs-popover` rule in hypr/rules.lua; the scrim is painted
+    // here rather than added to that rule, the same way the cheatsheet does it.
+    WlrLayershell.namespace: "qs-popover-dock-picker"
+    WlrLayershell.layer: WlrLayer.Overlay
+    WlrLayershell.keyboardFocus: root.open
+        ? WlrKeyboardFocus.Exclusive
+        : WlrKeyboardFocus.None
+
+    // Stays mapped for the length of the close animation, or it vanishes
+    // instantly and only the opening is ever seen.
+    property bool mapped: false
+    visible: root.mapped
+
+    onOpenChanged: {
+        if (root.open) {
+            unmapTimer.stop();
+            root.mapped = true;
+            picker.grab();
+        } else {
+            unmapTimer.restart();
+        }
+    }
+
+    Timer {
+        id: unmapTimer
+        interval: Theme.durNormal
+        onTriggered: root.mapped = false
+    }
+
+    Rectangle {
+        anchors.fill: parent
+        color: Theme.alpha(Theme.bgDark, Theme.overlayAlpha)
+        opacity: root.open ? 1 : 0
+        Behavior on opacity { NumberAnimation { duration: Theme.durNormal; easing.type: Easing.OutCubic } }
+
+        MouseArea {
+            anchors.fill: parent
+            onClicked: ShellState.close()
+        }
+    }
+
+    Rectangle {
+        id: card
+
+        anchors.horizontalCenter: parent.horizontalCenter
+        // High rather than centred: the list grows downwards as you type, and a
+        // centred card walks up the screen while you are reading it.
+        y: Math.round(parent.height * 0.18)
+        width: Math.min(root.width - 120, 520)
+        height: header.height + picker.implicitHeight + 56
+
+        radius: Theme.popoverRadius
+        color: Theme.alpha(Theme.bgPopover, Theme.popoverAlpha)
+        border.width: 1
+        border.color: Theme.alpha(Theme.fg, 0.1)
+
+        opacity: root.open ? 1 : 0
+        scale: root.open ? 1 : 0.98
+        Behavior on opacity { NumberAnimation { duration: Theme.durNormal; easing.type: Easing.OutCubic } }
+        Behavior on scale { NumberAnimation { duration: Theme.durNormal; easing.type: Easing.OutCubic } }
+
+        PrismEdge {
+            anchors.top: parent.top
+            anchors.left: parent.left
+            anchors.right: parent.right
+            inset: Theme.popoverRadius
+        }
+
+        // Clicks on the card itself must not fall through to the scrim.
+        MouseArea { anchors.fill: parent }
+
+        Item {
+            id: header
+
+            anchors.top: parent.top
+            anchors.left: parent.left
+            anchors.right: parent.right
+            anchors.margins: 22
+            height: title.implicitHeight
+
+            Text {
+                id: title
+                text: "Add application to dock"
+                color: Theme.fg
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeLarge
+                font.weight: Font.DemiBold
+            }
+
+            Text {
+                anchors.right: parent.right
+                anchors.verticalCenter: title.verticalCenter
+                text: "Esc to close"
+                color: Theme.fgMuted
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+            }
+        }
+
+        DockAppPicker {
+            id: picker
+
+            anchors.top: header.bottom
+            anchors.topMargin: 16
+            anchors.left: parent.left
+            anchors.right: parent.right
+            anchors.leftMargin: 22
+            anchors.rightMargin: 22
+
+            pinned: Settings.dockPinned
+            onPicked: id => {
+                root.pin(id);
+                ShellState.close();
+            }
+        }
+    }
+
+    // A Shortcut rather than Keys.onEscapePressed on an item: the search box
+    // owns Escape while it has focus (it clears the query first), and a key
+    // handler on an ancestor would never see the second press.
+    Shortcut {
+        sequence: "Escape"
+        enabled: root.open
+        onActivated: ShellState.close()
+    }
+}
@@ -0,0 +1,271 @@
+// What a dock icon has open, shown after a dwell on hover.
+//
+// Its own surface, not something drawn inside the dock. The dock's input mask
+// is a thin strip when hidden and the bar's own rectangle when revealed;
+// widening it to cover a preview strip would hand the dock every click in the
+// empty space above it, which is most of the screen.
+//
+// Capture is one-shot -- `live: false` plus an explicit captureFrame() -- for
+// the same reason the overview's thumbnails are: streaming four windows for as
+// long as a pointer rests on an icon repaints continuously for nothing. The
+// deferral around that first capture is copied from
+// modules/overview/WindowThumbnail.qml, where the reasoning is written out.
+
+import Quickshell
+import Quickshell.Hyprland
+import Quickshell.Wayland
+import Quickshell.Widgets
+import QtQuick
+import qs.config
+
+PopupWindow {
+    id: root
+
+    // The DockItem being hovered, and the app object behind it. Both are
+    // written by the Dock from DockBody's dwell timer.
+    property Item anchorItem: null
+    property var app: null
+
+    // Which edge the dock lives on, so the strip appears on the side of the
+    // icon that faces the screen rather than off the edge.
+    property string position: "bottom"
+
+    readonly property bool vertical: root.position === "left" || root.position === "right"
+
+    // Four is the cap. A strip of previews wider than the screen is not a
+    // preview of anything, and the point of this surface is to answer "which
+    // window do I want" at a glance -- past four, the answer is the overview.
+    readonly property int previewCap: 4
+
+    readonly property var allWindows: root.app && root.app.windows ? root.app.windows : []
+    readonly property var windows: root.allWindows.length > root.previewCap
+        ? root.allWindows.slice(0, root.previewCap)
+        : root.allWindows
+
+    readonly property int overflow: root.allWindows.length - root.windows.length
+
+    // Read by the Dock, which feeds it back to DockBody's grace timer. Crossing
+    // from the icon to a preview leaves the dock entirely -- these are separate
+    // surfaces -- so without this the act of reaching for a preview closes it.
+    readonly property bool hovered: pointer.hovered
+
+    signal dismissed
+
+    // Bumped each time the strip opens; each bump re-captures, so a window that
+    // has changed since the last look is not shown as it was.
+    property int refreshToken: 0
+
+    anchor.item: root.anchorItem
+    // Bottom dock: above the icon. Side dock: alongside it, away from the edge.
+    anchor.edges: root.vertical
+        ? (root.position === "left" ? Edges.Right : Edges.Left)
+        : Edges.Top
+    anchor.gravity: root.vertical
+        ? (root.position === "left" ? Edges.Right : Edges.Left)
+        : Edges.Top
+    anchor.margins.bottom: root.vertical ? 0 : 10
+    anchor.margins.left: root.position === "left" ? 10 : 0
+    anchor.margins.right: root.position === "right" ? 10 : 0
+
+    implicitWidth: strip.implicitWidth + 12
+    implicitHeight: strip.implicitHeight + 12
+
+    color: "transparent"
+    visible: root.anchorItem !== null && root.windows.length > 0
+
+    // Deliberately NOT grabFocus. A grab would close the strip on the first
+    // click anywhere and take the pointer with it, which is exactly the
+    // gesture that is supposed to focus a window.
+    grabFocus: false
+
+    onVisibleChanged: {
+        if (root.visible)
+            root.refreshToken++;
+    }
+
+    function addressOf(toplevel: var): string {
+        const raw = String(toplevel?.address ?? "");
+        if (!raw)
+            return "";
+        return raw.startsWith("0x") ? raw : "0x" + raw;
+    }
+
+    function focusToplevel(toplevel: var): void {
+        if (!toplevel)
+            return;
+        if (toplevel.workspace)
+            toplevel.workspace.activate();
+
+        const address = root.addressOf(toplevel);
+        if (address)
+            Hyprland.dispatch(`hl.dsp.focus({ window = "address:${address}" })`);
+        else if (toplevel.wayland)
+            toplevel.wayland.activate();
+
+        root.dismissed();
+    }
+
+    HoverHandler {
+        id: pointer
+    }
+
+    Rectangle {
+        anchors.fill: parent
+        radius: Theme.popoverRadius
+        color: Theme.alpha(Theme.bgPopover, Theme.popoverAlpha)
+        border.width: 1
+        border.color: Theme.alpha(Theme.fg, 0.08)
+
+        Row {
+            id: strip
+            anchors.centerIn: parent
+            padding: 10
+            spacing: 8
+
+            Repeater {
+                model: root.windows
+
+                Rectangle {
+                    id: card
+
+                    required property var modelData
+
+                    readonly property var source: card.modelData ? card.modelData.wayland : null
+
+                    width: 176
+                    height: 132
+                    radius: Theme.cardRadius
+                    border.width: 0 // QTBUG-137166
+                    color: cardHover.hovered
+                        ? Theme.alpha(Theme.fg, Theme.hoverAlpha)
+                        : Theme.alpha(Theme.bg, 0.5)
+                    clip: true
+
+                    Item {
+                        id: frame
+                        anchors.left: parent.left
+                        anchors.right: parent.right
+                        anchors.top: parent.top
+                        anchors.bottom: caption.top
+                        anchors.margins: 6
+                        anchors.bottomMargin: 2
+
+                        // Shown until a frame arrives, and forever on a
+                        // compositor without screencopy -- an icon rather than
+                        // an empty box or an error.
+                        IconImage {
+                            anchors.centerIn: parent
+                            visible: root.app && root.app.entry && root.app.entry.icon
+                            source: root.app && root.app.entry && root.app.entry.icon
+                                ? (String(root.app.entry.icon).startsWith("/")
+                                    ? "file://" + root.app.entry.icon
+                                    : Quickshell.iconPath(root.app.entry.icon, true))
+                                : ""
+                            implicitSize: 32
+                            asynchronous: true
+                            mipmap: true
+                            opacity: shotLoader.hasFrame ? 0 : 1
+                        }
+
+                        Loader {
+                            id: shotLoader
+                            anchors.fill: parent
+
+                            readonly property bool hasFrame: item ? item.hasContent : false
+
+                            // Gated on refreshToken for the reason spelled out
+                            // in WindowThumbnail: a ScreencopyView created
+                            // before its surface has mapped has no recording
+                            // context, and its first capture fails silently.
+                            active: !!card.source && root.refreshToken > 0
+                            sourceComponent: shotComponent
+                        }
+
+                        Component {
+                            id: shotComponent
+
+                            ScreencopyView {
+                                id: shot
+                                captureSource: card.source
+                                live: false
+                                paintCursor: false
+                                constraintSize: Qt.size(frame.width, frame.height)
+
+                                readonly property real aspect: sourceSize.height > 0
+                                    ? sourceSize.width / sourceSize.height
+                                    : 16 / 9
+
+                                anchors.centerIn: parent
+                                width: Math.min(parent.width, parent.height * aspect)
+                                height: aspect > 0 ? width / aspect : parent.height
+                                opacity: hasContent ? 1 : 0
+
+                                property bool recordingReady: false
+
+                                function tryCapture(): void {
+                                    if (shot.hasContent)
+                                        return;
+                                    if (!shot.recordingReady) {
+                                        frameReady.restart();
+                                        return;
+                                    }
+                                    shot.captureFrame();
+                                }
+
+                                // One frame of the popup's own rendering is
+                                // what makes the capture context exist.
+                                FrameAnimation {
+                                    id: frameReady
+                                    running: false
+                                    onTriggered: {
+                                        running = false;
+                                        if (shot.hasContent)
+                                            return;
+                                        shot.recordingReady = true;
+                                        shot.tryCapture();
+                                    }
+                                }
+
+                                Component.onCompleted: tryCapture()
+                            }
+                        }
+                    }
+
+                    Text {
+                        id: caption
+                        anchors.bottom: parent.bottom
+                        anchors.left: parent.left
+                        anchors.right: parent.right
+                        anchors.margins: 7
+                        text: String(card.modelData?.title ?? "").trim() || (root.app ? root.app.appId : "")
+                        elide: Text.ElideRight
+                        horizontalAlignment: Text.AlignHCenter
+                        color: Theme.fgDim
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSizeSmall
+                    }
+
+                    HoverHandler {
+                        id: cardHover
+                    }
+
+                    TapHandler {
+                        onTapped: root.focusToplevel(card.modelData)
+                    }
+                }
+            }
+
+            // Only when there are more windows than fit. Says so rather than
+            // silently showing four of nine.
+            Text {
+                anchors.verticalCenter: parent.verticalCenter
+                visible: root.overflow > 0
+                width: visible ? implicitWidth : 0
+                text: "+" + root.overflow
+                color: Theme.fgMuted
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+            }
+        }
+    }
+}
@@ -25,7 +25,7 @@ Pill {
    Text {
        anchors.verticalCenter: parent.verticalCenter
        text: FocusSession.remainingText
-        color: FocusSession.paused ? Theme.fgDim : Theme.fg
+        color: FocusSession.paused ? Theme.barFgDim : Theme.barFg
        font.family: Theme.fontFamily
        font.features: Theme.tabularFigures
        font.pixelSize: Theme.fontSizeSmall
@@ -56,6 +56,11 @@ Rectangle {

    // Critical notifications get a red edge rather than a color wash, so the
    // text contrast never changes.
+    //
+    // Read through Notifs.effectiveUrgency rather than off the notification, so
+    // an application the rules treat as critical is marked here too -- and one
+    // demoted to low is not. The bell, the popup timeout and the Do Not Disturb
+    // breakthrough all ask the same question the same way.
    Rectangle {
        anchors.left: parent.left
        anchors.top: parent.top
@@ -65,7 +70,7 @@ Rectangle {
        radius: 1.5
        border.width: 0
        color: Theme.urgent
-        visible: root.notification.urgency === NotificationUrgency.Critical
+        visible: Notifs.effectiveUrgency(root.notification) === NotificationUrgency.Critical
    }

    readonly property var defaultAction: {
@@ -85,17 +90,43 @@ Rectangle {
        return false;
    }

-    // Everything except the buttons: clicking the body runs the notification's
-    // default action, which is what GNOME does.
+    // A command the notification carried as data, in the `panama-exec` hint.
+    // Panama's escalation ladder rides this: a crash watcher that has already
+    // exited, or an install that failed in a terminal, still gets a clickable
+    // "diagnose this with your agent" -- the command IS the notification, so
+    // nothing has to stay alive to service an action and the click survives a
+    // shell restart. Read once at delivery; see services/Notifs.qml for why
+    // that is safe and what it deliberately does not promise.
+    readonly property string execCommand: Notifs.execCommand(root.notification)
+
+    readonly property bool bodyActivates: root.defaultAction !== null || root.execCommand !== ""
+
+    // Clicking the body runs the notification's default action, which is what
+    // GNOME does. The sender's own action wins when a notification carries
+    // both: an application that registered one is asking for ITS handler, and
+    // the hint exists for senders that cannot stay alive to serve one.
+    //
+    // The command runs through `sh -c` because it arrives as a single string
+    // rather than an argv -- that is the shape the hint can carry. It runs
+    // detached, so a notification click never blocks or outlives the shell.
+    function activateBody(): void {
+        if (root.defaultAction) {
+            root.defaultAction.invoke();
+            return;
+        }
+        if (root.execCommand === "")
+            return;
+        Quickshell.execDetached(["sh", "-c", root.execCommand]);
+        root.dismissed();
+    }
+
+    // Everything except the buttons.
    MouseArea {
        id: hover
        anchors.fill: parent
        hoverEnabled: true
-        cursorShape: root.defaultAction ? Qt.PointingHandCursor : Qt.ArrowCursor
-        onClicked: {
-            if (root.defaultAction)
-                root.defaultAction.invoke();
-        }
+        cursorShape: root.bodyActivates ? Qt.PointingHandCursor : Qt.ArrowCursor
+        onClicked: root.activateBody()
    }

    IconImage {
@@ -146,12 +177,20 @@ Rectangle {
        id: settingsMenu
        anchorItem: settingsMenuButton

-        // A Column already measures itself from its children, and in Qt 6 both
-        // implicit sizes are read-only on a positioner -- assigning them makes
-        // the whole shell fail to load rather than just this menu.
+        // Popover's container is a plain Item and does not size itself from its
+        // children, so the window dimensions come from the column's implicit
+        // size — the same pattern TrayMenu uses. Rows take their *actual* width
+        // from the window in the other direction; the two chains are
+        // independent, so there is no binding loop.
+        implicitWidth: Math.max(menuBody.implicitWidth + contentPadding * 2, 200)
+        implicitHeight: menuBody.implicitHeight + contentPadding * 2
+
        Column {
+            id: menuBody
+            width: parent.width
+
            TrayMenuRow {
-                id: notificationSettings
+                width: parent.width
                label: "Notification settings"
                onActivated: {
                    ShellState.openSettings("notifications");
@@ -12,7 +12,13 @@ import qs.services
 PanelWindow {
    id: root

-    visible: !Notifs.doNotDisturb && Notifs.popups.length > 0
+    // Whether a notification is allowed to be a banner is decided once, in
+    // Notifs.handleNotification: a focus mode's allow-list and the
+    // critical-breakthrough switch are both exceptions to Do Not Disturb, and
+    // anything they let past is already in `popups`. Re-testing doNotDisturb
+    // here would override that three-way decision and leave an allowed app
+    // chiming at an empty screen.
+    visible: Notifs.popups.length > 0
    color: "transparent"

    anchors.top: true
@@ -0,0 +1,168 @@
+// The visual bell: one flash at the edges of the screen when a notification
+// arrives that would have rung.
+//
+// For people who cannot hear the bell. It fires on exactly the notifications
+// services/Notifs.qml calls bell-eligible -- same per-application switch, same
+// low-urgency rule, same suppress-sound hint -- but NOT on the event-sounds
+// switch, which would make this do nothing for the person it is for. That rule
+// is pinned in Notifs.qml above `bellWouldRing`; this file only listens.
+//
+// Edges rather than the whole screen. A full-screen white flash is what X11's
+// visual bell did, and it is genuinely unpleasant: it destroys dark adaptation,
+// hides the thing you were reading at the moment it demands attention, and is
+// the shape of flash that photosensitivity guidance warns about. A soft glow
+// inward from the four edges is unmissable in peripheral vision and leaves the
+// middle of the screen -- the part being read -- alone.
+//
+// ONE animation per notification. There is no `loops`, no Timer that restarts
+// it, and a burst of notifications cannot stack flashes: while the animation is
+// running, further triggers are ignored outright. A strobing screen is a
+// seizure risk, not a notification.
+
+import Quickshell
+import Quickshell.Wayland
+import QtQuick
+import qs.config
+import qs.services
+
+PanelWindow {
+    id: root
+
+    property var modelData: null
+    screen: root.modelData
+
+    // Mapped only while flashing. The rest of the session this costs nothing,
+    // and no surface sits over the desktop waiting for something to happen.
+    property bool mapped: false
+    visible: root.mapped
+
+    anchors.top: true
+    anchors.bottom: true
+    anchors.left: true
+    anchors.right: true
+
+    // Reserve nothing and respect nothing: the glow is drawn over the whole
+    // output including under the bar and the dock, which is what makes it
+    // visible from wherever the eyes happen to be.
+    exclusiveZone: 0
+    exclusionMode: ExclusionMode.Ignore
+    color: "transparent"
+
+    WlrLayershell.namespace: "qs-visual-bell"
+    WlrLayershell.layer: WlrLayer.Overlay
+    WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+
+    // Entirely click-through: an empty mask means no part of this surface
+    // takes a pointer event, so a flash cannot swallow the click you were in
+    // the middle of making.
+    mask: Region {}
+
+    // How far the glow reaches in from each edge. Fixed pixels rather than a
+    // share of the screen: this is about peripheral vision, which does not
+    // scale with the size of the monitor.
+    readonly property int reach: 72
+
+    // Deliberately NOT Theme.durFast / Theme.durNormal. Those collapse to zero
+    // when Reduce motion is on, which would make the flash instantaneous and
+    // therefore invisible -- switching on Reduce motion would silently switch
+    // off Visual alerts. A flash is information, not decoration, so it keeps
+    // its own timings. They are slow enough not to strobe and quick enough to
+    // be over before it becomes irritating.
+    readonly property int riseMs: 110
+    readonly property int fallMs: 340
+
+    Connections {
+        target: Notifs
+        function onBellEligible(notification: var): void { root.flash(); }
+    }
+
+    // The one-shot. A trigger arriving mid-flash is dropped rather than
+    // queued or restarted, so ten notifications landing together are one
+    // flash -- the same coalescing the audible bell gets from its throttle.
+    function flash(): void {
+        if (!Settings.visualAlerts || pulse.running)
+            return;
+        root.mapped = true;
+        pulse.restart();
+    }
+
+    Item {
+        id: glow
+
+        anchors.fill: parent
+        opacity: 0
+
+        readonly property color tint: Theme.alpha(Theme.accent, 0.62)
+        readonly property color fade: Theme.alpha(Theme.accent, 0)
+
+        Rectangle {
+            anchors.top: parent.top
+            anchors.left: parent.left
+            anchors.right: parent.right
+            height: root.reach
+            gradient: Gradient {
+                GradientStop { position: 0.0; color: glow.tint }
+                GradientStop { position: 1.0; color: glow.fade }
+            }
+        }
+
+        Rectangle {
+            anchors.bottom: parent.bottom
+            anchors.left: parent.left
+            anchors.right: parent.right
+            height: root.reach
+            gradient: Gradient {
+                GradientStop { position: 0.0; color: glow.fade }
+                GradientStop { position: 1.0; color: glow.tint }
+            }
+        }
+
+        Rectangle {
+            anchors.left: parent.left
+            anchors.top: parent.top
+            anchors.bottom: parent.bottom
+            width: root.reach
+            gradient: Gradient {
+                orientation: Gradient.Horizontal
+                GradientStop { position: 0.0; color: glow.tint }
+                GradientStop { position: 1.0; color: glow.fade }
+            }
+        }
+
+        Rectangle {
+            anchors.right: parent.right
+            anchors.top: parent.top
+            anchors.bottom: parent.bottom
+            width: root.reach
+            gradient: Gradient {
+                orientation: Gradient.Horizontal
+                GradientStop { position: 0.0; color: glow.fade }
+                GradientStop { position: 1.0; color: glow.tint }
+            }
+        }
+    }
+
+    // Up, down, gone. One sequence, run once per notification: no `loops`, no
+    // repeat, and the window unmaps itself at the end so nothing is left over
+    // the desktop between notifications.
+    SequentialAnimation {
+        id: pulse
+
+        NumberAnimation {
+            target: glow
+            property: "opacity"
+            from: 0
+            to: 1
+            duration: root.riseMs
+            easing.type: Easing.OutCubic
+        }
+        NumberAnimation {
+            target: glow
+            property: "opacity"
+            to: 0
+            duration: root.fallMs
+            easing.type: Easing.InCubic
+        }
+        ScriptAction { script: root.mapped = false }
+    }
+}
@@ -26,6 +26,11 @@ function iconFor(kind, ratio) {
        return "audio-input-microphone-symbolic";
    if (name === "brightness")
        return "display-brightness-symbolic";
+    // The magnifier, stepped from SUPER+ALT+= / - / 0. Ratio 0 is 1.00 ×,
+    // which is the magnifier switched off, so it gets the "actual size" icon
+    // rather than a magnifying glass claiming to be magnifying.
+    if (name === "zoom")
+        return ratio <= 0 ? "zoom-original-symbolic" : "zoom-in-symbolic";
    if (name === "media-play" || name === "media-playing")
        return "media-playback-start-symbolic";
    if (name === "media-pause" || name === "media-paused")
@@ -94,6 +94,34 @@ PanelWindow {
                wrapMode: Text.WordWrap
            }

+            // The caller's stated reason, when panama-sudo passed one.
+            // Untrusted commentary from an unprivileged process, so it is
+            // labeled as a claim and drawn beside polkitd's message above --
+            // never in place of it. The real action text is the trust anchor.
+            Column {
+                width: parent.width
+                visible: Polkit.statedReason !== ""
+                spacing: 2
+
+                Text {
+                    text: "Stated reason (unverified)"
+                    color: Theme.fgMuted
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSizeSmall
+                    font.weight: Font.DemiBold
+                }
+
+                Text {
+                    width: parent.width
+                    text: Polkit.statedReason
+                    color: Theme.fgDim
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSize
+                    font.italic: true
+                    wrapMode: Text.WordWrap
+                }
+            }
+
            Text {
                width: parent.width
                visible: Polkit.users.length > 1
--- a/Show More
+++ b/Show More