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,53 @@
+# Coming from another desktop
+
+Panama is Hyprland with a shell built to replace a GNOME session, so most of
+what you know still applies. The differences worth knowing on day one are
+below. Nothing here is a preference you have to accept: every one of them is
+adjustable in Settings.
+
+## Windows arrange themselves
+
+The biggest change. You do not drag windows into position. Open a second
+window and the screen splits; open a third and it splits again. This is
+called tiling, and after a day of it, dragging windows feels like making
+your own bed in a hotel.
+
+Two things follow from it:
+
+- **There is no minimise.** A minimised window is a window you have hidden
+  from a layout that was managing it for you. Use `Super + Shift + X` to
+  push a window to the scratchpad and `Super + X` to bring it back, which is
+  the same idea without the layout losing track of it.
+- **Floating still exists.** `Super + Ctrl + C` makes a window float above
+  the layout, for the dialog that was never meant to be tiled.
+
+## Workspaces replace the taskbar
+
+Instead of many windows on one screen, use many screens. `Alt + 1` through
+`Alt + 0` jump straight to a workspace; `Alt + Shift + 1` sends the window
+you are looking at to workspace one. `Super + backtick` shows all of them at
+once.
+
+If you came from macOS, this is Spaces with the friction removed. If you came
+from Windows, it is virtual desktops that are actually worth using because
+switching is one key rather than three.
+
+## The launcher is the menu
+
+There is no applications menu to browse. `Super + Space` opens a search box
+that finds applications, files, clipboard history, emoji, and does
+arithmetic. Type three letters of what you want.
+
+This replaces the Start menu, Spotlight, the GNOME overview's app grid, and
+the run dialog, and it is faster than all of them because it never asks you
+to aim at anything.
+
+## What stayed the same
+
+`Super + Tab` still switches windows. The bar is still along the top with a
+clock in the middle and status on the right. There is still a dock. Volume
+and brightness keys still work, and still work on the lock screen. Copy and
+paste are unchanged. Your files are where you left them.
+
+GNOME Settings is still installed for the few panels Panama deliberately does
+not own, and Panama's own Settings hands off to it where that applies.
@@ -0,0 +1,46 @@
+# The keyboard
+
+Press `Super + /` at any time to see every shortcut this machine has. That
+list is generated from the live keymap, so it is never out of date, and it
+includes anything you have rebound.
+
+This chapter is the shape behind that list, which is the part worth learning
+once.
+
+## Three modifiers, three jobs
+
+| Modifier | Acts on |
+|---|---|
+| `Super` | The window you are looking at |
+| `Alt` | Workspaces |
+| `Super + Ctrl` | The layout itself: splitting, floating, swapping |
+
+Almost every shortcut follows from this. `Super + H` moves focus left.
+`Alt + H` moves to the workspace on the left. `Super + Ctrl + H` swaps the
+window leftward in the layout.
+
+## Directions
+
+`H`, `J`, `K`, `L` mean left, down, up, right, as they do in vim. The arrow
+keys work everywhere the letters do, so you never have to learn them if you
+would rather not.
+
+Add `Shift` to move the window rather than the focus. `Super + Shift + L`
+takes the current window and moves it to the right.
+
+## The handful worth memorising first
+
+| Keys | What it does |
+|---|---|
+| `Super + Space` | Find and open anything |
+| `Super + T` | Terminal |
+| `Super + Q` | Close the window |
+| `Super + backtick` | Every window, every workspace |
+| `Super + I` | Settings |
+| `Super + /` | Every other shortcut |
+
+## Changing them
+
+Settings has a Shortcuts page listing every bind, each of which can be
+reassigned. A rebind moves the shortcut and cannot change what it does, so
+there is no way to make a key do something unexpected by editing it.
@@ -0,0 +1,48 @@
+# Windows and workspaces
+
+## How the split is chosen
+
+A new window splits the space of the window that had focus. Whether it splits
+beside or below depends on which way that space is longer, which usually
+matches what you were about to do anyway.
+
+When it does not, `Super + Ctrl + G` flips the split of the focused window,
+and `Super + Ctrl + Z` and `Super + Ctrl + V` decide the direction the *next*
+window will take before you open it.
+
+## Resizing
+
+`Super + Shift` plus `Y`, `O`, `B`, `M` adjusts width; `I`, `U`, `N` and
+comma adjust height. These are inverted from what their letters suggest, on
+purpose, and the reason is written in `config/dot/hypr/keybinds.lua` next to
+the binds.
+
+For anything finer, hold `Super` and drag with the right mouse button.
+
+## Fullscreen and floating
+
+`Super + U` makes the focused window fullscreen. `Super + Ctrl + C` lifts it
+out of the layout to float, and `Super + Ctrl + Shift + C` pins it so it
+follows you between workspaces. A floating window can be moved by holding
+`Super` and dragging with the left button.
+
+## Workspaces
+
+Ten of them, on `Alt + 1` through `Alt + 0`. `Alt + H` and `Alt + L` step
+between neighbours, and `Alt + Shift` plus a number sends the current window
+somewhere without following it.
+
+On a machine with more than one display, workspaces belong to whichever
+screen has focus. If you would rather pin workspaces one through ten to your
+main display and give the second screen its own, that is a switch on the
+Desktop settings page.
+
+## Projects
+
+A project is the set of windows you open together: which applications, which
+workspace each was on, and for a terminal, which directory it was in.
+
+Arrange things the way you want them, then run **Save Layout as Project**
+from the launcher. **Open Project** lays it out again on free workspaces, so
+it never lands on top of what you are already doing. An application that
+refuses to open twice is moved into place rather than launched again.
@@ -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.
@@ -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.