1 files changed, 56 insertions, 0 deletions
diff --git a/desktop/modules/hyprland/README.md b/desktop/modules/hyprland/README.md
new file mode 100644
index 0000000..278a3b4
--- /dev/null
+++ b/desktop/modules/hyprland/README.md
@@ -0,0 +1,56 @@
+# hyprland
+
+Two settings pages, under Hyprland in the settings window.
+
+## Keyboard shortcuts
+
+Every bind Hyprland has loaded, from `hyprctl binds -j`, joined to the
+`hl.bind` call in `~/.config/hypr` (`hyprland.lua` and `sections/*.lua`)
+that made it: by description, then by combo, then, for a bind built in a
+loop, by the longest literal head of its description. hyprctl reports every
+Lua action as an opaque `__lua` number, so the action shown is the source's.
+
+List shows the combo, the description and action, and the file:line. Source
+shows the files holding binds, line-numbered. Clashes lists combos bound
+more than once in the same submap.
+
+Clicking a row opens its combo for editing when the source writes it as a
+plain string, or one built from file-level string locals (`mainMod .. " +
+w"`). Save asks Hyprland first, by `hyprctl eval` of a do-nothing bind on the
+new combo, which fails on an unknown modifier or keysym. Then the first
+argument of that call is replaced with the combo as a string literal, and
+Hyprland's autoreload picks up the file. An edit is refused if the call is
+no longer where it was parsed. A bind built at run time says where to change
+it instead.
+
+## Options
+
+All of Hyprland's options from `hyprctl descriptions -j`, with values from
+one batched `getoption`, filtered by everything, set in the config, or
+changed from the default. Values differing from the default are in the
+accent, gradients show their colours.
+
+A change is one line in `sections/keystone.lua`, which `hyprland.lua`
+requires last, so it wins over the hand-written sections without editing
+them:
+
+    hl.config({ general = { border_size = 4 } }) -- keystone: general:border_size
+
+The line is run through `hyprctl eval` first, which refuses an unknown key or
+a value of the wrong shape and changes nothing; one that passes applies at
+once and is then written. Booleans and enums are picked from their choices,
+everything else is typed as a Lua expression, started from the current value
+(`{ top = 8, right = 8, bottom = 8, left = 8 }` for gaps, `{ colors = {
+"rgba(...)" }, angle = 45 }` for a gradient). Reset drops the line, and the
+reload brings back what the other sections, or the default, give it.
+
+Not handled: an option a hand-written section sets is shadowed, not edited
+there; and the two options `getoption` cannot read show as unreadable and
+cannot be edited.
+
+## Check
+
+    node desktop/modules/hyprland/test_hypr.js
+
+It also checks every live bind finds its source, when `~/.config/hypr` is
+there.