# When something breaks

## Start here

Run **Check System Health** from the launcher, or open Settings and go to
System Health. 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 Shortcuts settings page 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. Every change there reverts itself after fifteen
seconds unless you confirm it, so a mode your monitor cannot show cannot
strand you. 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 settings page can roll the system back
where btrfs snapshots are configured.

## Reporting it

`panama doctor` produces a redacted summary suitable for pasting into an
issue. It deliberately omits tokens, hostnames and account details.