# When something breaks

## Start here

Run **Check System Health** from the launcher, or open Settings and go to
System, then the System Health tab. 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 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. 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 colour, 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.

## 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, the Snapshots tab under System in Settings 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.