Write the manual for the person using the desktop

docs/ is engineering artifacts -- design specs, plans, an upstream
ledger -- and none of it is written for the person who has to live
here. Five chapters that are: coming from another desktop, the
keyboard, windows and workspaces, when something breaks, and making it
yours.

Rendered inside Settings rather than opened in a browser, so a chapter
that says "the Displays page reverts after fifteen seconds" is one
click from the Displays page. Qt's markdown renderer does the work;
one chapter per Text, because Text has an implicit texture size limit
and a document long enough to hit it goes blank rather than
complaining.

The chapters live beside the shell in manual/ rather than at the
repository root, which departs from the plan. The reason is the path:
the shell finds them through Quickshell.shellDir, which is correct
wherever the repository is, whereas walking upward out of the shell
directory is only correct by accident. The contract fails that pattern
if it comes back.

The contract also pins the set both ways -- every chapter listed
exists, every chapter that exists is listed -- because a renamed file
shows an error card where a chapter should be, which reads as a broken
manual rather than as a moved file.

config/dot/quickshell/manual/04-when-something-breaks.md

@@ -0,0 +1,56 @@
+# 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.