# 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.
