repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: add archlinux hypr and experimentation skills

b2475a867bc7be27f3af413542d30a992f7d9aaa

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (18)

TODO.md

Modified
2 2 # TODO
4 4 ## Skills
6 -- hypr:
7 - hyprland ecosystem and configs
8 -- archlinux
9 -- experiment:
10 - creating prototypes and experimenting, then cleaning up
11 -- linux console
13 6 ## Extensions
15 8 - [ ] Port agent identity plugin from opencode?

skills/archlinux/SKILL.md

Added
new file mode 100644
1 +---
2 +name: archlinux
3 +description: "Use for Arch Linux system help: configuring the OS, pacman/package management, upgrades, maintenance, AUR/PKGBUILD/makepkg, boot/service/package/software troubleshooting. Not Raspberry Pi or generic Linux unless Arch-specific."
4 +---
6 +# Arch Linux
8 +Arch-specific system/config/troubleshooting/pkg help.
9 +Keep volatile facts out of memory; fetch current docs.
11 +## Route
13 +- System/maintenance/upgrade → `references/system.md`
14 +- Config changes/mirrors/hooks → `references/config.md`
15 +- Troubleshooting failures → `references/troubleshooting.md`
16 +- Software/pkg/AUR/build issues → `references/software.md`
18 +## Fresh Truth
20 +Local first:
22 +```sh
23 +man pacman pacman.conf makepkg PKGBUILD alpm-hooks paccache pacdiff
24 +```
26 +Web when local docs missing/stale:
28 +```text
29 +https://man.archlinux.org/man/<page>.<section>.en
30 +https://wiki.archlinux.org/title/<Topic>
31 +https://archlinux.org/news/
32 +https://archlinux.org/packages/
33 +https://aur.archlinux.org/
34 +```
36 +Before upgrade advice:
37 +check Arch News.
38 +For exact package/repo/current syntax:
39 +use current man/wiki/package pages, not memory.
41 +## Local Wiki
43 +If offline/frequent Arch work, check:
45 +```sh
46 +pacman -Qq arch-wiki-docs arch-wiki-lite wikiman 2>/dev/null
47 +```
49 +If absent, suggest installing one.
50 +Do not require it.
52 +## Safety
54 +- No partial upgrades.
55 + Avoid `pacman -Sy <pkg>`; use full upgrade flow.
56 +- If `-Sy` happened and `-Su` failed:
57 + resolve + complete upgrade before other pkg ops.
58 +- AUR = untrusted user content.
59 + Inspect `PKGBUILD`, `*.install`, patches before build.
60 +- `.pacnew`/`.pacsave` need manual merge; never blind overwrite.
61 +- Avoid unless current Arch News/wiki explicitly says so:
62 + `--overwrite`, `-Rdd`, `--nodeps`, blind `--noconfirm`.
63 +- Do not symlink libraries to fix soname errors; complete/recover upgrade.
65 +## Root Delegation
67 +Do not run root/admin mutations yourself unless user explicitly authorizes.
68 +Give exact command for user to run.
69 +Detect user's shell first for syntax compatibility:
71 +```sh
72 +printf 'SHELL=%s\n' "$SHELL"
73 +getent passwd "$(id -un)" | cut -d: -f7
74 +```
76 +Command style:
78 +- unknown/fish/nu → one simple command per line; avoid arrays, functions,
79 + process substitution, brace expansion.
80 +- env vars → use `env VAR=value command` for portability.
81 +- complex flow → write tiny script or split steps.
82 +- state impact + rollback/log path before mutating `/etc`, pacman DB, boot,
83 + services.

skills/archlinux/references/config.md

Added
new file mode 100644
1 +# Arch Config
3 +Use for `/etc`, pacman config, repos, mirrors, hooks, service/package config.
5 +## Before Changing
7 +Classify:
9 +- file path
10 +- owning package
11 +- live reload/restart needed?
12 +- backup/rollback path
13 +- root required?
15 +Read-only probes:
17 +```sh
18 +pacman -Qo /path/to/file
19 +pacman -Qii package
20 +systemctl cat unit.service
21 +systemctl status unit.service --no-pager
22 +```
24 +If root edit needed, delegate via user's shell.
25 +Prefer editor-safe command, e.g. `sudoedit /etc/file` when appropriate.
27 +## Pacman Config
29 +Current truth:
30 +`man pacman.conf`, wiki `Pacman`.
32 +Stable rules:
34 +- Main config:
35 + `/etc/pacman.conf`.
36 +- Mirror list commonly included from `/etc/pacman.d/mirrorlist`.
37 +- Repository order matters when packages share names.
38 +- Directives are case-sensitive/CamelCase.
39 +- `NoUpgrade`/`NoExtract` paths are archive paths:
40 + no leading `/`.
41 +- Hooks are non-interactive; system hooks live under
42 + `/usr/share/libalpm/hooks/`, admin hooks commonly under
43 + `/etc/pacman.d/hooks/`.
44 +- Signature policy/current defaults:
45 + verify with `man pacman.conf`, do not weaken casually.
47 +## Mirrors/Repos
49 +For stale/404/target-not-found problems, inspect:
51 +```sh
52 +grep -v '^#' /etc/pacman.conf
53 +grep -v '^#' /etc/pacman.d/mirrorlist | head
54 +```
56 +Use current wiki `Mirrors`/`Reflector` before recommending tooling.
57 +After repo config changes, full upgrade before installing new packages.
59 +## Service/Software Config
61 +- Check package docs + Arch Wiki page for that software.
62 +- Check ownership before editing generated/package-owned files.
63 +- Prefer drop-ins over modifying unit files directly.
64 +- State reload command separately:
65 + e.g. daemon reload, service restart, app reload.
67 +## Current Sources
69 +- Man:
70 + `pacman.conf(5)`, `alpm-hooks(5)`, `pacman(8)`
71 +- Wiki:
72 + `Pacman`, `Mirrors`, target software page

skills/archlinux/references/software.md

Added
new file mode 100644
1 +# Arch Software
3 +Use for pacman, packages, AUR, PKGBUILD, makepkg, app install/build issues.
5 +## Pacman Query Map
7 +```sh
8 +pacman -Ss term # sync DB search
9 +pacman -Si package # sync pkg info
10 +pacman -Qs term # installed search
11 +pacman -Qi package # installed pkg info
12 +pacman -Ql package # installed files
13 +pacman -Qo /path/file # file owner
14 +pacman -Qm # foreign/local/AUR
15 +pacman -Qtdq # orphan deps
16 +pacman -F path # remote file owner; needs files DB
17 +```
19 +Refresh files DB only when needed:
20 +`pacman -Fy`.
22 +## Install/Remove
24 +- Install from repos:
25 + `pacman -S package` if DB current; otherwise full upgrade flow.
26 +- Full upgrade:
27 + `pacman -Syu`.
28 +- Install local pkg:
29 + `pacman -U ./pkg.pkg.tar.zst`.
30 +- Remove package + unneeded deps:
31 + `pacman -Rs package`.
32 +- Avoid `-Rsc`, `-Rdd`, `--nodeps`, `--overwrite` unless explicitly justified.
33 +- Use `--print`/`--print-format` for dry/processable transaction previews.
35 +## AUR
37 +AUR is unsupported/untrusted user content.
38 +Agent must inspect before build/install:
40 +```sh
41 +less PKGBUILD
42 +ls -la
43 +git diff @~..@ # if updating existing clone
44 +```
46 +Check for:
48 +- unexpected network/code exec in build funcs
49 +- dangerous `install` scripts
50 +- checksum/PGP handling
51 +- bundled patches
52 +- dependency sanity
54 +Build rules:
56 +- `base-devel` is assumed by AUR packages.
57 +- Run `makepkg` as normal user, never root.
58 +- `makepkg -s` can install repo deps via pacman; AUR deps need separate
59 + handling.
60 +- `makepkg --verifysource` checks sources without building.
61 +- `makepkg --printsrcinfo` for metadata.
62 +- Clean chroot helps distinguish user-env failure from broken PKGBUILD.
64 +AUR helpers do not remove review duty.
66 +## PKGBUILD Facts
68 +Current truth:
69 +`man PKGBUILD`, `man makepkg`.
70 +Durable basics:
72 +- PKGBUILD is Bash sourced by `makepkg`; treat as executable code.
73 +- Minimal fields include `pkgname`, `pkgver`, `pkgrel`, `arch`.
74 +- `package()` installs into `$pkgdir`; `prepare()`, `build()`, `check()`
75 + optional.
76 +- `backup=()` controls pacnew/pacsave behavior for config files.
77 +- `source=()` + checksums/PGP define source verification.
78 +- Split packages use multiple `pkgname`s and `package_name()` funcs.
80 +## Current Sources
82 +- Man:
83 + `pacman(8)`, `makepkg(8)`, `PKGBUILD(5)`, `makepkg.conf(5)`
84 +- Wiki:
85 + `Pacman`, `Arch User Repository`, `Creating packages`, `Makepkg`
86 +- Live:
87 + `archlinux.org/packages`, `aur.archlinux.org`

skills/archlinux/references/system.md

Added
new file mode 100644
1 +# Arch System
3 +Use for system state, maintenance, upgrades, health.
5 +## First Read-only Probes
7 +```sh
8 +cat /etc/os-release
9 +uname -a
10 +pacman -Q pacman 2>/dev/null
11 +systemctl --failed
12 +journalctl -b --no-pager -p warning..alert
13 +pacman -Qm
14 +pacman -Qtdq
15 +```
17 +Do not infer Arch from `pacman` alone; read `/etc/os-release`.
19 +## Upgrade Discipline
21 +- Read `https://archlinux.org/news/` before upgrade guidance.
22 +- Full upgrades only:
23 + `pacman -Syu`.
24 +- Never advise `pacman -Sy <pkg>`.
25 +- Keep rescue/live media in mind for risky kernel/boot/glibc/systemd updates.
26 +- After upgrade:
27 + review pacman output, handle `.pacnew`, restart affected services or reboot.
28 +- AUR/local packages are user's responsibility; rebuild when deps/ABI change.
30 +## Maintenance Checks
32 +```sh
33 +systemctl --failed
34 +journalctl -b --no-pager
35 +pacman -Qtdq # orphan deps
36 +pacman -Qm # foreign/local/AUR packages
37 +pacman -Qkk # file integrity; can be noisy
38 +```
40 +Package cache:
42 +- Prefer `paccache` from `pacman-contrib` over aggressive `pacman -Scc`.
43 +- Preserve rollback ability unless disk pressure is real.
45 +Config drift:
47 +```sh
48 +find /etc -name '*.pacnew' -o -name '*.pacsave'
49 +grep -E '\.pac(new|save)' /var/log/pacman.log
50 +```
52 +Use `pacdiff` if present.
54 +## Current Sources
56 +- Wiki:
57 + `System maintenance`, `Pacman`, `Pacman/Pacnew and Pacsave`
58 +- Man:
59 + `pacman(8)`, `paccache(8)`, `pacdiff(8)`

skills/archlinux/references/troubleshooting.md

Added
new file mode 100644
1 +# Arch Troubleshooting
3 +Use for boot, service, package transaction, upgrade, and app failures.
4 +Start read-only.
5 +Identify last change.
7 +## Baseline
9 +```sh
10 +cat /etc/os-release
11 +uname -a
12 +systemctl --failed
13 +journalctl -b --no-pager -p err..alert
14 +tail -n 80 /var/log/pacman.log
15 +```
17 +For app issue:
19 +```sh
20 +command -v app
21 +pacman -Qo "$(command -v app)"
22 +pacman -Qi package
23 +```
25 +If command substitution conflicts with user shell, split into two commands.
27 +## Package Transaction Errors
29 +Lock:
31 +- Verify no pacman/makepkg/AUR helper process is running before removing lock.
32 +- Current lock path/safe handling:
33 + check wiki/man.
35 +Conflicting files:
37 +```sh
38 +pacman -Qo /path/to/conflict
39 +```
41 +If unowned, investigate origin before rename/delete.
42 +Avoid `--overwrite` unless current Arch guidance says so.
44 +Target not found / retrieval failed:
46 +- Verify package exists:
47 + `archlinux.org/packages`, `pacman -Ss`, AUR if unofficial.
48 +- Check enabled repos + mirror freshness.
49 +- Do not fix with `pacman -Sy <pkg>`.
51 +Invalid/corrupt package/signature:
53 +- Check current wiki `Pacman/Package signing` + Arch News.
54 +- Suspect stale keyring, partial downloads, bad mirror only after evidence.
56 +Interrupted upgrade / broken pacman / unbootable:
58 +- Fetch current wiki `Pacman#Troubleshooting` before procedural advice.
59 +- Prefer live ISO + mount + `arch-chroot`/`--sysroot` recovery path.
60 +- Reconstruct exact failed transaction from `/var/log/pacman.log` when relevant.
62 +## Software Failures
64 +Classify:
66 +- packaging issue?
67 + upstream bug?
68 + config?
69 + missing optional dep?
70 + partial upgrade?
71 + service sandbox?
72 + permissions?
74 +Probes:
76 +```sh
77 +pacman -Qi package
78 +pacman -Ql package | less
79 +pacman -Qii package
80 +journalctl -b --user --no-pager
81 +journalctl -b --no-pager -u unit.service
82 +```
84 +Missing `.so` after upgrades usually means partial/incomplete upgrade or
85 +unrebuilt local/AUR package.
86 +Do not symlink libs.
88 +## Output Shape
90 +```text
91 +Observed: ...
92 +Likely cause: ...
93 +Evidence: ...
94 +Safe checks: ...
95 +User-run root step, if needed: ...
96 +Rollback/logs: ...
97 +```

skills/experimentation/SKILL.md

Added
new file mode 100644
1 +---
2 +name: experimentation
3 +description: "Use when agent is about to create/run throwaway code or generated artifacts—scratch scripts, spikes, probes, PoCs, one-off parsers/converters, microbenchmarks, API/dependency behavior checks—to answer a narrow technical question. Enforces falsifiable hypothesis, controls/baselines, independent verification, provenance, promote-or-delete, and cleanup. Do not use for normal feature implementation/review, permanent project tests, or web research without scratch code/artifacts."
4 +---
6 +# Experimentation
8 +Temp code = experiment.
9 +Learn → verify → promote/delete → clean.
11 +## Trigger
13 +Use iff task creates/runs throwaway code/data/artifacts:
15 +- scratch scripts/files, spikes, probes, PoCs
16 +- microbenchmarks, migration dry-runs
17 +- one-off parsers/converters/generators
18 +- API/dependency/env behavior checks
19 +- temp fixtures/logs/output dirs to answer 1 question
21 +Do **not** use for normal impl/review/tests except exploratory phase.
23 +## Protocol
25 +### 1. Hypothesis
27 +Before code/run:
29 +```text
30 +Q: ...
31 +H: if <condition/change/input> → <observable> because <reason>
32 +Falsifier: false if <specific obs>
33 +Control/baseline: ...
34 +Cmd/input/env: ...
35 +Artifacts: <temp paths>
36 +Cleanup: delete <paths> unless promoted
37 +```
39 +Unfalsifiable H ⇒ rewrite.
41 +### 2. Isolation
43 +Default:
44 +outside repo.
46 +```bash
47 +tmp="$(mktemp -d "${TMPDIR:-/tmp}/pi-exp.XXXXXX")"
48 +printf '%s\n' "$tmp"
49 +```
51 +Repo only when needed:
53 +- single obvious dir:
54 + `.pi/tmp/<slug>/` | `tmp/<slug>/`
55 +- record every ignored/untracked path
56 +- `git status --short` before+after
58 +No scattered scratch files.
60 +### 3. Provenance
62 +Record if result matters:
64 +- exact cmd(s), inputs, sample data
65 +- tool/runtime/dependency versions; lockfile state
66 +- env/config/flags/params
67 +- random seed(s); nondeterminism notes
68 +- commit hash if git
69 +- timing context:
70 + hw/load/warmup/repeats
72 +Prefer executable protocol over prose:
73 +cmd/test/mise task/script/fixture.
75 +### 4. Verification ladder
77 +Use ≥2 independent checks when possible.
79 +1. Predict output before run.
80 +2. Positive control:
81 + known-good passes.
82 +3. Negative control:
83 + known-bad fails.
84 +4. Edge cases:
85 + empty/min/max/weird.
86 +5. Assertions/invariants fail loud.
87 +6. Cross-check via 2nd method/tool/manual sample.
88 +7. Rerun:
89 + deterministic or bounded variance.
90 +8. Seed randomness or report variance.
91 +9. Compare baseline/current vs changed.
92 +10. Explain mismatch; unresolved ⇒ inconclusive.
94 +1 green run = weak evidence.
95 +Log/screenshot without cmd provenance = weak.
97 +### 5. Promote | summarize | delete
99 +Classify every artifact:
101 +- **Promote**:
102 + durable test/fixture/doc/bench harness/script/repro.
103 +- **Summarize**:
104 + learned fact only → response/issue/commit msg.
105 +- **Delete**:
106 + temp script/output/cache/log/download/build product.
108 +Promotion requirements:
110 +- named project location; no local abs paths/debug prints
111 +- minimal fixture size
112 +- conforms to fmt/lint/test conventions
114 +## Cleanup
116 +Before final answer:
118 +1. Stop started processes.
119 +2. Delete created scratch files/dirs/outputs/logs/caches/dumps/ad-hoc fixtures.
120 +3. Keep only explicitly promoted artifacts.
121 +4. `git status --short` if git.
122 +5. Explain/ask about unknown leftovers.
124 +Delete rule:
126 +```text
127 +Only delete explicit paths created by this experiment.
128 +Never delete user data, research cache, repo files, broad globs, or git-clean without confirmation.
129 +```
131 +Final report shape:
133 +```text
134 +Result: supported | falsified | inconclusive
135 +Evidence: cmd(s) + checks
136 +Promoted: <paths + why>
137 +Cleaned: <paths>
138 +Remaining: <intentional dirty paths>
139 +```
141 +## Smells
143 +- `test.py`/`scratch.js`/`out.json`/`log.txt` in repo root
144 +- hidden generated dir no owner
145 +- real data mutated vs copied sample
146 +- manual step not captured
147 +- bench no warmup/repeats/context
148 +- randomness no seed/variance
149 +- claim from 1 happy path
150 +- broad cleanup:
151 + `rm -rf *`, `git clean -fdx` sans consent
153 +## Basis
155 +Distilled from reproducible computational research + SE artifact work:
157 +- Sandve 2013:
158 + result provenance; avoid manual data edits; version scripts; record
159 + intermediates/seeds.
160 +- Wilson 2017:
161 + project org; generated files in results dirs; explicit deps; VCS; recorded
162 + processing.
163 +- NASEM 2019:
164 + reproducibility needs inputs, executable methods, params, env,
165 + nondeterministic intermediates.
166 +- Beaulieu-Jones/Greene 2017:
167 + continuous analysis = rerun + env/log capture; emulate lightly for spikes.
168 +- ICSE artifact studies ≤2026:
169 + availability ≠ executability ≠ reproducibility; failures:
170 + env drift, weak docs, missing deps, unstructured artifacts.

skills/hypr/SKILL.md

Added
new file mode 100644
1 +---
2 +name: hypr
3 +description: "Configure, understand, or troubleshoot a Hyprland Wayland desktop and Hypr ecosystem: hyprland.lua/hyprland.conf, hyprctl, monitors, workspaces, binds, dispatchers, window/workspace rules, input, autostart, portals/screenshare, hyprpaper/hyprlock/hypridle/hyprsunset/hyprpolkitagent, plus Wayland-only bars/launchers/notifications/clipboard/screenshots. Use when user mentions Hyprland, HyprWM, ~/.config/hypr, hyprctl, hypr* desktop tools, or Hyprland rice/dotfiles. Not for Hyper-V, hypervisors, hyperparameters, generic Wayland, Sway/niri, X11-only WMs, or Raspberry Pi."
4 +license: MIT
5 +compatibility: "Hyprland/HyprWM Wayland desktop; Linux; version-sensitive config syntax"
6 +---
8 +# Hypr — Hyprland desktop
10 +Hyprland is a dynamic tiling Wayland compositor.
11 +Config root is usually `~/.config/hypr/`.
12 +Current + old dotfiles differ; detect installed version + config syntax before
13 +editing.
14 +Stay Wayland-only.
16 +## First response checklist
18 +1. Identify target:
19 + - compositor config:
20 + `hyprland.lua` | legacy `hyprland.conf`
21 + - tool config:
22 + `hyprpaper.conf`, `hyprlock.conf`, `hypridle.conf`, `hyprsunset.conf`,
23 + `xdph.conf`
24 + - external component:
25 + bar/launcher/notification/portal/etc.
26 +2. Inspect user's files before prescribing.
27 +3. Check live state when troubleshooting:
28 + ```bash
29 + hyprctl version
30 + hyprctl monitors all
31 + hyprctl clients -j
32 + hyprctl devices
33 + hyprctl binds
34 + hyprctl activewindow
35 + hyprctl instances
36 + ```
37 +4. Verify docs for installed version.
38 + Official wiki targets current/-git; old configs may use old syntax.
39 +5. Avoid X11 advice unless user explicitly asks about XWayland compatibility.
40 + Prefer native Wayland apps/protocols.
42 +## Core concepts
44 +- **Hyprland** owns outputs, workspaces, windows, input, binds, rules, layout,
45 + animations.
46 +- **Dispatchers** are compositor actions used by keybinds/scripts via config or
47 + `hyprctl`.
48 +- **Rules** match windows/workspaces and apply behavior.
49 + Order matters.
50 +- **Layer-shell clients** draw desktop UI:
51 + bars, launchers, notifications, wallpapers, lock screens.
52 +- **Portals + PipeWire** provide screencast/file-picker/global-shortcut
53 + integration to apps.
54 +- **Hypr ecosystem** provides first-party helpers; prefer them when they fit.
56 +## Delegate by task
58 +| Task | Read |
59 +| ----------------------------------------------------------- | ---------------------------------- |
60 +| Up-to-date docs/version commands | `references/upstream.md` |
61 +| Choose overlapping desktop tools | `references/ecosystem-taxonomy.md` |
62 +| Hyprland config syntax/basics | `references/config-basics.md` |
63 +| Hypr ecosystem tool configs | `references/hypr-tools.md` |
64 +| Troubleshooting portals, screenshare, input, rules, startup | `references/troubleshooting.md` |
65 +| Dotfile/rice structure patterns | `references/dotfiles-patterns.md` |
67 +## Editing rules
69 +- Do not rewrite a user's entire rice unless asked.
70 +- Preserve syntax family:
71 + Lua config stays Lua; legacy hyprlang stays legacy.
72 +- Prefer small config modules and comments over monolith edits.
73 +- Never install/start competing daemons without saying what it replaces.
74 +- For config copied from GitHub, treat as inspiration, not authoritative.

skills/hypr/references/config-basics.md

Added
new file mode 100644
1 +# Hyprland config basics
3 +Config is version-sensitive.
4 +Preserve user's syntax.
6 +## Detect syntax family
8 +```bash
9 +ls ~/.config/hypr/
10 +hyprctl version
11 +```
13 +Common cases:
15 +- `hyprland.lua`:
16 + current Lua-style config.
17 +- `hyprland.conf`:
18 + legacy hyprlang config; still common in dotfiles.
19 +- Split configs under `~/.config/hypr/conf/`, `hyprland/`, `custom/`, etc.
21 +Do not convert between syntax families unless asked.
23 +## Core config areas
25 +| Area | Controls | Live inspection |
26 +| --------------- | -------------------------------------------------------------- | ------------------------ |
27 +| monitors | output mode/position/scale/VRR/HDR/disable/mirror | `hyprctl monitors all` |
28 +| input/devices | keyboard layout, touchpad, mouse, per-device overrides | `hyprctl devices` |
29 +| binds | key/mouse/switch/global shortcuts | `hyprctl binds`, `wev` |
30 +| dispatchers | focus/move/resize/workspace/exec/window actions | `hyprctl dispatch ...` |
31 +| window rules | match class/title/tag/etc.; float, opacity, workspace, no_blur | `hyprctl clients -j` |
32 +| workspace rules | monitor binding, gaps, default names, layout per workspace | `hyprctl workspaces` |
33 +| layouts | dwindle/master/monocle/scrolling behavior | `hyprctl layouts` |
34 +| decoration | gaps, border, rounding, opacity, shadow, blur | `hyprctl getoption ...` |
35 +| animations | bezier/animation tree | `hyprctl animations` |
36 +| env/autostart | session env, daemons, app startup | `systemctl --user`, logs |
38 +## Current Lua-style snippets
40 +Use only if user's config is Lua-style/current.
42 +```lua
43 +-- ~/.config/hypr/hyprland.lua
44 +require("conf.monitors")
45 +require("conf.input")
46 +require("conf.binds")
47 +require("conf.rules")
49 +hl.config({
50 + general = {
51 + gaps_in = 5,
52 + gaps_out = 10,
53 + border_size = 2,
54 + layout = "dwindle",
55 + },
56 + decoration = {
57 + rounding = 8,
58 + blur = { enabled = true, size = 6, passes = 2 },
59 + },
60 +})
61 +```
63 +Monitor:
65 +```lua
66 +hl.monitor({ output = "", mode = "preferred", position = "auto", scale = 1 })
67 +hl.monitor({ output = "DP-1", mode = "2560x1440@144", position = "0x0", scale = 1 })
68 +```
70 +Bind:
72 +```lua
73 +hl.bind("SUPER + Return", hl.dsp.exec_cmd("foot"), { description = "terminal" })
74 +hl.bind("SUPER + D", hl.dsp.exec_cmd("hyprlauncher"), { description = "launcher" })
75 +hl.bind("SUPER + Q", hl.dsp.window.close())
76 +hl.bind("SUPER + mouse:272", hl.dsp.window.drag(), { mouse = true })
77 +hl.bind("SUPER + mouse:273", hl.dsp.window.resize(), { mouse = true })
78 +```
80 +Autostart:
82 +```lua
83 +hl.on("hyprland.start", function()
84 + hl.exec_cmd("hyprpaper")
85 + hl.exec_cmd("hypridle")
86 + hl.exec_cmd("waybar")
87 +end)
88 +```
90 +Window rule:
92 +```lua
93 +hl.window_rule({
94 + match = { class = "firefox", title = "Picture-in-Picture" },
95 + float = true,
96 + pin = true,
97 + size = { 480, 270 },
98 +})
99 +```
101 +Workspace rule:
103 +```lua
104 +hl.workspace_rule({ workspace = "name:code", monitor = "DP-1", default = true })
105 +hl.workspace_rule({ workspace = "w[tv1]s[false]", gaps_in = 0, gaps_out = 0 })
106 +```
108 +Environment:
110 +```lua
111 +hl.env("XDG_CURRENT_DESKTOP", "Hyprland")
112 +hl.env("XDG_SESSION_TYPE", "wayland")
113 +hl.env("QT_QPA_PLATFORM", "wayland;xcb")
114 +```
116 +If using UWSM, prefer UWSM env files over compositor config env.
118 +## Legacy hyprlang clues
120 +Common in older dotfiles.
121 +Do not paste current Lua into these files.
123 +```ini
124 +source = ~/.config/hypr/conf/*.conf
126 +monitor = , preferred, auto, 1
128 +bind = SUPER, Return, exec, foot
129 +bind = SUPER, Q, killactive
130 +bindm = SUPER, mouse:272, movewindow
131 +bindm = SUPER, mouse:273, resizewindow
133 +windowrule = float, class:^(pavucontrol)$
134 +windowrule = workspace 2, class:^(firefox)$
136 +exec-once = hyprpaper
137 +exec-once = hypridle
138 +exec-once = waybar
139 +```
141 +When legacy docs/examples disagree with current wiki, find versioned docs
142 +matching installed Hyprland.
144 +## Rules that save time
146 +- Output names change; use `hyprctl monitors all` or `desc:` matching for stable
147 + monitor rules.
148 +- Monitor positions use logical/scaled pixels; no overlap allowed.
149 +- For key names, use `wev`; for devices/switches, use `hyprctl devices`.
150 +- For app rules, match actual `class`/`title` from `hyprctl clients -j`.
151 +- Window rule order matters; specific before broad.
152 +- Some window effects are static at open; title changes after launch may not
153 + affect static rules.
154 +- For many `hyprctl` changes, batch instead of spamming synchronous calls.
155 +- `hyprctl reload` reloads config; if syntax family changed, `full-reset` may be
156 + needed.

skills/hypr/references/dotfiles-patterns.md

Added
new file mode 100644
1 +# Hypr dotfile patterns
3 +Use dotfiles as structure examples, not authority.
4 +Validate options against the installed Hyprland version and official docs.
6 +## Common layout
8 +```text
9 +~/.config/hypr/
10 +├── hyprland.lua | hyprland.conf
11 +├── conf/ | modules/ | custom/
12 +├── hyprpaper.conf
13 +├── hyprlock.conf
14 +├── hypridle.conf
15 +├── hyprsunset.conf
16 +└── xdg-desktop-portal-hyprland.conf
17 +```
19 +## Good structure
21 +- Small files by concern:
22 + monitors, input, binds, rules, autostart, env.
23 +- Host-specific monitor files or generated monitor include.
24 +- Clear comments for machine-specific device names.
25 +- One primary bar, launcher, notification daemon, lock/idle stack.
26 +- Theme/palette generator writes generated files into a clearly named generated
27 + directory.
29 +## Red flags
31 +- Current Lua snippets pasted into legacy hyprlang config or vice versa.
32 +- Multiple wallpaper/bar/notification/gamma daemons enabled at once.
33 +- X11-only tools in Wayland paths (`xclip`, `xsel`, `scrot`, `xrandr`).
34 +- Hard-coded monitor names copied from someone else's machine.
35 +- Blind `exec-once` pile with no service/log ownership.
36 +- Unreviewed GitHub install scripts for rice dependencies.
38 +## Safe adaptation workflow
40 +1. Inspect user's current tree and syntax.
41 +2. Identify one concern to change.
42 +3. Copy the smallest pattern, not a whole rice.
43 +4. Run `hyprctl reload` and inspect `hyprctl configerrors`.
44 +5. Verify live state (`hyprctl monitors all`, `clients -j`, `binds`).
45 +6. Keep rollback path:
46 + VCS, backup file, or reverted snippet.

skills/hypr/references/ecosystem-taxonomy.md

Added
new file mode 100644
1 +# Hyprland ecosystem taxonomy
3 +Goal:
4 +know what overlaps.
5 +Prefer `hypr*` when first-party and sufficient.
6 +Use one primary per overlapping category.
8 +## Compositor/session
10 +| Role | Prefer | Alternatives | Overlap |
11 +| ------------------ | ---------------------------- | ------------------------------------ | --------------------------------------------- |
12 +| Wayland compositor | Hyprland | none in this skill | Not Sway/niri/river advice |
13 +| Session manager | plain Hyprland launch / UWSM | display manager session | UWSM changes env/autostart/shutdown semantics |
14 +| Shutdown/logout UI | hyprshutdown | wlogout, custom rofi/quickshell menu | one menu frontend; commands may be shared |
16 +## Required desktop plumbing
18 +| Role | Prefer | Alternatives | Notes |
19 +| ------------------ | --------------------------- | ------------------------------------ | ----------------------------------------------- |
20 +| Portal/screencast | xdg-desktop-portal-hyprland | none for Hyprland features | stack with generic portal + file picker backend |
21 +| File picker portal | xdg-desktop-portal-gtk | xdg-desktop-portal-kde | XDPH does not own file picker |
22 +| Audio/video graph | PipeWire + WirePlumber | distro-specific PipeWire launcher | required for screen share |
23 +| 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 +## Hypr first-party user apps
28 +| Role | Prefer | Alternatives | Overlap |
29 +| -------------------- | ---------------------------------- | ----------------------------------------------------------------- | ----------------------------------------- |
30 +| Wallpaper | hyprpaper | swaybg, wpaperd, swww/awww, mpvpaper | one wallpaper daemon per output |
31 +| Color picker | hyprpicker | wl-color-picker, grim+slurp scripts | same global picker role |
32 +| Idle manager | hypridle | swayidle | idle daemon; pairs with lock/suspend cmds |
33 +| Lock screen | hyprlock | swaylock, gtklock | lock app; not same as idle daemon |
34 +| Blue-light/gamma | hyprsunset | wlsunset, gammastep where Wayland works | avoid simultaneous gamma filters |
35 +| App launcher | hyprlauncher | fuzzel, walker, rofi-wayland, wofi, tofi, bemenu, anyrun, vicinae | many can coexist; choose one primary bind |
36 +| System info | hyprsysteminfo | inxi, fastfetch | diagnostic frontend |
37 +| Password UI | hyprpwcenter | pass/secret-service frontends | optional |
38 +| Qt integration/theme | hyprland-qt-support, hyprqt6engine | qt5ct/qt6ct, Kvantum | toolkit theming overlap |
40 +## Bars, panels, shells
42 +| Role | Common choices | Notes |
43 +| --------------------- | ------------------------------------ | -------------------------------------------- |
44 +| Simple bar | Waybar, ashell | Waybar has Hyprland modules; config JSON/CSS |
45 +| Desktop shell/widgets | Quickshell, AGS/Astal, Eww, Noctalia | usually one shell owns bar/sidebar/OSD/menus |
46 +| Dock | nwg-dock-hyprland, custom shell dock | overlaps with bar/shell launchers |
48 +Avoid running multiple bars/panels unless user wants it.
49 +Duplicate layer-shell surfaces cause reserved-area/weird layout issues.
51 +## Launchers/menus
53 +| Type | Tools | Notes |
54 +| ------------------- | -------------------------------------------------------------- | ---------------------------------------------------------- |
55 +| App launcher | hyprlauncher, fuzzel, walker, rofi-wayland, wofi, tofi, bemenu | primary `SUPER+D`/`SUPER+R` target |
56 +| Multi-module runner | walker, anyrun, vicinae, rofi scripts | apps/windows/web/clipboard/calculator |
57 +| Power menu | hyprshutdown, wlogout, rofi/waybar/quickshell custom | frontend only; real actions are loginctl/systemctl/hyprctl |
59 +## Wallpaper/color/theming chain
61 +| Role | Tools | Overlap |
62 +| ------------------ | ------------------------------------------------------- | -------------------------------------- |
63 +| Wallpaper daemon | hyprpaper, swww/awww, swaybg, wpaperd, mpvpaper | one daemon |
64 +| Wallpaper selector | waypaper, wallrizz, custom rofi/quickshell scripts | frontend; controls daemon |
65 +| Palette generator | wallust, matugen, pywal | one source of truth preferred |
66 +| Toolkit theme | GTK theme/nwg-look, qt5ct/qt6ct, Kvantum, hyprqt6engine | toolkit-specific |
67 +| Cursor | hyprcursor themes, xcursor env fallback | compositor/toolkit consistency matters |
69 +## 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 |
79 +Avoid `xclip`, `xsel`, X11 screenshot tools.
81 +## Clipboard
83 +| Role | Tools | Notes |
84 +| ------------- | ------------------------------------ | ------------------------------------------- |
85 +| CLI clipboard | wl-clipboard (`wl-copy`, `wl-paste`) | base primitive |
86 +| History | cliphist | usually paired with rofi/fuzzel/wofi/walker |
87 +| Persistence | wl-clip-persist | keeps clipboard after source exits |
88 +| GUI manager | CopyQ Wayland mode | heavier, own UI |
90 +## Applets/non-Hypr basics
92 +| Role | Tools |
93 +| ------------- | --------------------------------------------------- |
94 +| Network | NetworkManager + nm-applet / nmtui |
95 +| Bluetooth | blueman-applet / blueberry |
96 +| Audio | WirePlumber + wpctl/pavucontrol |
97 +| Brightness | brightnessctl/light |
98 +| Secrets | gnome-keyring / keepassxc / kwallet depending stack |
99 +| Terminals | foot, kitty, alacritty, ghostty, wezterm |
100 +| File managers | nautilus, dolphin, thunar, yazi/lf |
102 +These are not Hyprland-specific; keep advice minimal unless integration breaks.

skills/hypr/references/hypr-tools.md

Added
new file mode 100644
1 +# Hypr tools
3 +First-party Hypr apps are version-sensitive.
4 +Check installed tool help and the current Hypr wiki before copying config.
6 +## Common tools
8 +| Tool | Role | Notes |
9 +| ----------------- | ----------------- | --------------------------------------------- |
10 +| `hyprpaper` | wallpaper daemon | one wallpaper daemon per output stack |
11 +| `hyprlock` | lock screen | pair with `hypridle` for idle locking |
12 +| `hypridle` | idle daemon | runs lock/suspend/dim commands on timers |
13 +| `hyprsunset` | gamma/blue-light | avoid running with other gamma filters |
14 +| `hyprpolkitagent` | polkit auth agent | run one polkit agent |
15 +| `hyprpicker` | color picker | Wayland-native picker |
16 +| `hyprlauncher` | launcher | overlaps with fuzzel/walker/wofi/rofi-wayland |
18 +## Inspection
20 +```bash
21 +hyprpaper --help
22 +hyprlock --help
23 +hypridle --help
24 +hyprsunset --help
25 +systemctl --user status hyprpaper hypridle hyprsunset hyprpolkitagent
26 +journalctl --user -b | grep -Ei 'hyprpaper|hyprlock|hypridle|hyprsunset|polkit'
27 +```
29 +## Editing rules
31 +- Preserve the user's config format and module layout.
32 +- Do not start competing daemons silently.
33 +- State what each daemon replaces before enabling it.
34 +- Prefer `systemctl --user` units when the user's setup already uses user
35 + services; otherwise preserve compositor autostart style.
36 +- For lock/idle changes, describe emergency unlock/recovery path first.

skills/hypr/references/troubleshooting.md

Added
new file mode 100644
1 +# Hypr troubleshooting
3 +Start read-only.
4 +Collect version, live compositor state, logs, and recent config changes before
5 +editing.
7 +## Baseline probes
9 +```bash
10 +hyprctl version
11 +hyprctl monitors all
12 +hyprctl clients -j
13 +hyprctl devices
14 +hyprctl binds
15 +hyprctl instances
16 +journalctl --user -b | grep -Ei 'hypr|xdg-desktop-portal|pipewire|wireplumber|polkit'
17 +```
19 +## Config failures
21 +```bash
22 +hyprctl reload
23 +hyprctl configerrors
24 +```
26 +If reload fails:
28 +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:
32 + copy original file or commit/stash before edits.
34 +## Screenshare / portals
36 +```bash
37 +systemctl --user status xdg-desktop-portal-hyprland xdg-desktop-portal pipewire wireplumber
38 +journalctl --user -b -u xdg-desktop-portal-hyprland -u xdg-desktop-portal
39 +```
41 +Common classes:
43 +- wrong portal backend running
44 +- missing PipeWire/WirePlumber
45 +- app launched with stale env
46 +- sandbox/browser portal permission issue
48 +Do not recommend X11 capture tools for native Wayland screenshare.
50 +## Binds not firing
52 +```bash
53 +hyprctl binds
54 +hyprctl devices
55 +wev
56 +```
58 +Check key names, keyboard layout, duplicate binds, submaps, and whether the app
59 +needs a portal/global-shortcut path.
61 +## Window rules not matching
63 +```bash
64 +hyprctl clients -j
65 +hyprctl activewindow
66 +```
68 +Match actual class/title/app id.
69 +Prefer narrow rules.
70 +Explain order and regex scope when changing rules.
72 +## Output shape
74 +```text
75 +Observed: ...
76 +Evidence: ...
77 +Likely class: config | portal | input | rule | daemon | app/env
78 +Safe checks: ...
79 +Proposed edit: ...
80 +Rollback: ...
81 +```

skills/hypr/references/upstream.md

Added
new file mode 100644
1 +# Up-to-date Hyprland info
3 +Official docs move fast.
4 +Verify against installed version.
6 +## Local truth
8 +```bash
9 +hyprctl version # version, commit, flags
10 +hyprctl monitors all # output names/modes/scales/desc
11 +hyprctl clients -j # windows: class/title/address/workspace/rules clues
12 +hyprctl devices # keyboards, mice, switches, keymap device names
13 +hyprctl binds # active binds + descriptions
14 +hyprctl getoption <option> # live option value
15 +hyprctl reload # reload config
16 +hyprctl reload full-reset # only for syntax-family reset when needed
17 +hyprctl dispatch '...' # run dispatcher
18 +hyprctl eval '...' # eval Lua/current config expression
19 +```
21 +Use tool help for exact current CLI:
23 +```bash
24 +hyprctl --help
25 +hyprlock --help
26 +hypridle --help
27 +hyprpaper --help
28 +hyprsunset --help
29 +```
31 +Logs:
33 +```bash
34 +journalctl --user -b | grep -Ei 'hypr|xdg-desktop-portal|pipewire|wireplumber'
35 +systemctl --user status xdg-desktop-portal-hyprland xdg-desktop-portal pipewire wireplumber
36 +```
38 +## Official sources
40 +- Wiki current:
41 + `https://wiki.hypr.land/`
42 +- Versioned wiki:
43 + `https://wiki.hypr.land/<version>/...`
44 +- Wiki source:
45 + `https://github.com/hyprwm/hyprland-wiki/tree/main/content`
46 +- Hyprland source/example config:
47 + `https://github.com/hyprwm/Hyprland`
48 +- Hypr ecosystem org:
49 + `https://github.com/hyprwm`
51 +Key wiki areas:
53 +- `Configuring/Start`
54 +- `Configuring/Basics/Variables`
55 +- `Configuring/Basics/Monitors`
56 +- `Configuring/Basics/Binds`
57 +- `Configuring/Basics/Dispatchers`
58 +- `Configuring/Basics/Window-Rules`
59 +- `Configuring/Basics/Workspace-Rules`
60 +- `Configuring/Advanced and Cool/Using-hyprctl`
61 +- `Useful Utilities/Must-have`
62 +- `Useful Utilities/Status-Bars`, `App-Launchers`, `Wallpapers`,
63 + `Screenshots-and-Recording`, `Screen-Sharing`
64 +- `Hypr Ecosystem/*`
66 +## Version-sensitive docs workflow
68 +1. Run `hyprctl version`.
69 +2. Look at user's config filename + syntax.
70 +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.
74 +## Research dotfiles safely
76 +Good GitHub search terms:
78 +```text
79 +Hyprland dotfiles hyprlock hypridle hyprpaper waybar
80 +Hyprland dotfiles quickshell walker swaync hyprsunset
81 +site:github.com Hyprland-Dots config/hypr hyprland.lua
82 +```
84 +Treat dotfiles as examples of structure/taxonomy only.
85 +Validate every option against official docs + installed version.

skills/linux-console/SKILL.md

Modified
53 53 infocmp -1 linux
56 -For deeper lookup: `references/research.md`.
56 +For deeper lookup:
57 +`references/research.md`.
58 59 ## Durable Rules
69 70 For every proposed change, state:
71 -- target: current VT | all VTs | boot/persistent
72 -- mechanism: escape seq | terminfo | kbd tool | system config | ioctl
73 -- privilege needs: none | user permissions | root/admin | unknown until probed
72 +- target:
73 + current VT | all VTs | boot/persistent
74 +- mechanism:
75 + escape seq | terminfo | kbd tool | system config | ioctl
76 +- privilege needs:
77 + none | user permissions | root/admin | unknown until probed
74 78 - rollback/reset path
76 80 ## Safety

skills/linux-console/references/model.md

Modified
2 2 # Model
4 4 ## Terms
6 -- Linux console: kernel console implementation.
7 -- Virtual console / VT: numbered console, usually `/dev/ttyN`.
8 -- pty: pseudo-terminal, usually `/dev/pts/N`; not a real VT.
9 -- `TERM=linux`: terminfo name commonly used by Linux VTs.
10 -- framebuffer console / `fbcon`: kernel console display path on many systems.
6 +- Linux console:
7 + kernel console implementation.
8 +- Virtual console / VT:
9 + numbered console, usually `/dev/ttyN`.
10 +- pty:
11 + pseudo-terminal, usually `/dev/pts/N`; not a real VT.
12 +- `TERM=linux`:
13 + terminfo name commonly used by Linux VTs.
14 +- framebuffer console / `fbcon`:
15 + kernel console display path on many systems.
12 17 ## Detection
22 27 /dev/pts/N
25 -Use exact user wording too: `tty1`, `tty2`, `virtual console`, `linux console`,
26 -`Ctrl+Alt+F1`, `getty`, `fbcon`.
30 +Use exact user wording too:
31 +`tty1`, `tty2`, `virtual console`, `linux console`, `Ctrl+Alt+F1`, `getty`,
32 +`fbcon`.
28 34 ## Terminfo
41 47 `clear` normally clears/redraws screen state.
43 -`reset` reinitializes terminal state via terminfo reset strings. It may undo
44 -palette/display state. Confirm through `infocmp -1 linux` and `man reset`.
49 +`reset` reinitializes terminal state via terminfo reset strings.
50 +It may undo palette/display state.
51 +Confirm through `infocmp -1 linux` and `man reset`.
46 53 ## Escape Controls
60 67 ## Screen Memory
62 69 `vcs(4)` documents `/dev/vcsN` and `/dev/vcsaN` screen-memory devices.
63 -They can help inspect or dump VTs. Access depends on device permissions.
70 +They can help inspect or dump VTs.
71 +Access depends on device permissions.
64 72 Prefer `setterm --dump` for simple snapshots when available.
66 74 ## Low-level ioctls
68 76 `ioctl_console(2)` describes Linux-specific console/VT ioctls and warns they are
69 -internal-ish. Prefer user tools unless low-level work is requested.
77 +internal-ish.
78 +Prefer user tools unless low-level work is requested.

skills/linux-console/references/research.md

Modified
49 49 - <https://man7.org/linux/man-pages/man4/vcs.4.html>
50 50 - <https://man7.org/linux/man-pages/man2/ioctl_console.2.html>
52 -Distro docs can explain policy/integration. Prefer upstream man pages for
53 -interfaces, distro wiki for packaging/persistence quirks.
52 +Distro docs can explain policy/integration.
53 +Prefer upstream man pages for interfaces, distro wiki for packaging/persistence
54 +quirks.

skills/linux-console/references/tools.md

Modified
14 14 Common scopes:
16 -- foreground/background/rendering attrs: current terminal stream
17 -- `--store`: stored defaults for reset-to-default on virtual consoles
18 -- blanking, bell, repeat, kernel messages: virtual-console-specific controls
16 +- foreground/background/rendering attrs:
17 + current terminal stream
18 +- `--store`:
19 + stored defaults for reset-to-default on virtual consoles
20 +- blanking, bell, repeat, kernel messages:
21 + virtual-console-specific controls
20 23 State exact scope before changing.
33 36 dumpkeys | head
36 -Critical scope: `loadkeys` changes the kernel keymap used by virtual consoles;
37 -check local docs for exact reach and permissions.
39 +Critical scope:
40 +`loadkeys` changes the kernel keymap used by virtual consoles; check local docs
41 +for exact reach and permissions.
39 43 Rollback idea: