repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: harden hypr troubleshooting guidance

25cef909dabcce09dc761bbc823b8793c2534146

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

skills/hypr/SKILL.md

Modified
11 11 Config root is usually `~/.config/hypr/`.
12 12 Current + old dotfiles differ; detect installed version + config syntax before
13 13 editing.
14 +Broken/in-transition setups are normal.
14 15 Stay Wayland-only.
16 17 ## First response checklist
33 34 hyprctl devices
34 35 hyprctl binds
35 36 hyprctl activewindow
37 + hyprctl configerrors
36 38 hyprctl instances
41 + If `HYPRLAND_INSTANCE_SIGNATURE` is missing, derive it from `hyprctl
42 + instances` and retry with that env var.
39 44 4. Verify docs for installed version.
40 45 Official wiki targets current/-git; old configs may use old syntax.
41 46 5. Avoid X11 advice unless user explicitly asks about XWayland compatibility.
65 70 `references/config-basics.md`
66 71 - Hypr ecosystem tool configs:
67 72 `references/hypr-tools.md`
68 -- Troubleshooting portals, screenshare, input, rules, startup:
73 +- Broken configs, migrations, portals, input, rules, startup:
69 74 `references/troubleshooting.md`
70 75 - Dotfile/rice structure patterns:
71 76 `references/dotfiles-patterns.md`

skills/hypr/references/config-basics.md

Modified
18 18 legacy hyprlang config; still common in dotfiles.
19 19 - Split configs under `~/.config/hypr/conf/`, `hyprland/`, `custom/`, etc.
21 -Do not convert between syntax families unless asked.
21 +Hyprland 0.55+ docs emphasize Lua, but many working/broken setups still keep
22 +legacy `hyprland.conf`.
23 +Treat that as migration state.
24 +Do not convert or mix syntax families unless asked.
23 26 ## Core config areas
144 147 ## Rules that save time
149 +- Run `hyprctl configerrors` before adding features; fix parser errors first.
146 150 - Output names change; use `hyprctl monitors all` or `desc:` matching for stable
147 151 monitor rules.
148 152 - Monitor positions use logical/scaled pixels; no overlap allowed.

skills/hypr/references/ecosystem-taxonomy.md

Modified
3 3 # Hyprland ecosystem taxonomy
5 5 Goal:
6 6 know what overlaps.
7 7 Prefer `hypr*` when first-party and sufficient.
8 +If user already chose a non-Hypr Wayland tool, preserve that choice unless it
9 +conflicts or is obsolete.
8 10 Use one primary per overlapping category.
10 12 ## Compositor/session
21 23 | File picker portal | xdg-desktop-portal-gtk | xdg-desktop-portal-kde | XDPH does not own file picker |
22 24 | Audio/video graph | PipeWire + WirePlumber | distro-specific PipeWire launcher | required for screen share |
23 25 | Polkit auth | hyprpolkitagent | polkit-kde-agent, GNOME polkit agent | run one agent |
24 -| Notifications | swaync | mako, dunst, fnott | run one daemon; swaync also notification center |
26 +| Notifications | mako / swaync | dunst, fnott | run one daemon; swaync adds notification center |
26 28 ## Hypr first-party user apps
69 71 ## Screenshots/recording/screenshare
71 -| Role | Prefer/typical | Alternatives | Notes |
72 -| -------------- | ----------------------------- | --------------------- | ----------------------------- |
73 -| Screenshot raw | grim + slurp | HyprCapture, hyprshot | Wayland-native capture |
74 -| Annotate | satty | swappy | consumes screenshot pipe/file |
75 -| Clipboard | wl-copy/wl-paste | cliphist frontend | Wayland clipboard |
76 -| Recording | wf-recorder | wl-screenrec, OBS | OBS uses PipeWire/portal |
77 -| Screenshare | XDPH + PipeWire + WirePlumber | browser/app portal UI | portal config/logs matter |
73 +| Role | Prefer/typical | Alternatives | Notes |
74 +| -------------- | ----------------------------- | --------------------- | ------------------------------ |
75 +| Screenshot raw | grim + slurp | hyprshot, HyprCapture | Wayland-native capture |
76 +| Annotate | satty | swappy, Flameshot | Flameshot usually needs portal |
77 +| Clipboard | wl-copy/wl-paste | cliphist frontend | Wayland clipboard |
78 +| Recording | wf-recorder | wl-screenrec, OBS | OBS uses PipeWire/portal |
79 +| Screenshare | XDPH + PipeWire + WirePlumber | browser/app portal UI | portal config/logs matter |
79 81 Avoid `xclip`, `xsel`, X11 screenshot tools.

skills/hypr/references/troubleshooting.md

Modified
12 12 hyprctl clients -j
13 13 hyprctl devices
14 14 hyprctl binds
15 +hyprctl configerrors
15 16 hyprctl instances
16 17 journalctl --user -b | grep -Ei 'hypr|xdg-desktop-portal|pipewire|wireplumber|polkit'
20 +If `HYPRLAND_INSTANCE_SIGNATURE` is missing, derive it from `hyprctl instances`
21 +and rerun probes with that env var.
19 23 ## Config failures
21 25 ```bash
26 30 If reload fails:
28 32 1. Identify syntax family (`hyprland.lua` vs legacy `hyprland.conf`).
29 -2. Check current/versioned wiki for that syntax.
30 -3. Bisect included config files or recent dotfile changes.
31 -4. Keep rollback:
33 +2. If Hyprland is newer than config style, classify as migration state.
34 +3. Check current/versioned wiki for that syntax.
35 +4. Fix parse errors before feature work.
36 +5. Bisect included config files or recent dotfile changes.
37 +6. Keep rollback:
32 38 copy original file or commit/stash before edits.
34 40 ## Screenshare / portals

skills/hypr/references/upstream.md

Modified
12 12 hyprctl devices # keyboards, mice, switches, keymap device names
13 13 hyprctl binds # active binds + descriptions
14 14 hyprctl getoption <option> # live option value
15 +hyprctl configerrors # current config errors
16 +hyprctl instances # running compositor instances
15 17 hyprctl reload # reload config
16 18 hyprctl reload full-reset # only for syntax-family reset when needed
17 19 hyprctl dispatch '...' # run dispatcher
18 20 hyprctl eval '...' # eval Lua/current config expression
23 +If Pi runs outside the Hyprland env and `hyprctl` says
24 +`HYPRLAND_INSTANCE_SIGNATURE not set`, use the instance list:
26 +```bash
27 +sig=$(hyprctl instances | awk '/^instance /{sub(":", "", $2); print $2; exit}')
28 +HYPRLAND_INSTANCE_SIGNATURE="$sig" hyprctl version
29 +```
31 +Use same env prefix for other `hyprctl` probes.
21 33 Use tool help for exact current CLI:
23 35 ```bash
68 80 1. Run `hyprctl version`.
69 81 2. Look at user's config filename + syntax.
70 82 3. If current wiki syntax differs, use versioned wiki matching user's version.
71 -4. If dotfile uses legacy syntax, do not blindly paste current Lua snippets.
72 -5. Prefer live introspection (`hyprctl ...`) over stale examples.
83 +4. If installed Hyprland is current but config is legacy, treat as migration
84 + state; do not mix syntax without explicit migration.
85 +5. If dotfile uses legacy syntax, do not blindly paste current Lua snippets.
86 +6. Prefer live introspection (`hyprctl ...`) over stale examples.
74 88 ## Research dotfiles safely