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.
2026-08-22 01:11:46 -04:00
parent 9202697734
commit 202b5b89ac
14 changed files with 459 additions and 2 deletions
@@ -0,0 +1,42 @@
+# Making it yours
+
+## Settings
+
+`Super + I`. Thirty-odd pages covering displays, sound, network, appearance,
+power, printers, users, sharing, storage, updates and the rest. The search
+box at the top searches the settings themselves rather than just page names,
+so if you know what you want to change you can type it.
+
+## Appearance
+
+Panama ships Tokyo Night Moon in a light and a dark variant, with eight
+accent colours. Changing either repaints the shell, the terminal, GTK
+applications, the lock screen and the system monitor at once.
+
+The wallpaper is per-monitor if you want it to be.
+
+## 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 update` will offer to commit it.