dots/HYDE-UPDATE.md

# Updating HyDE on a host

Operational runbook for the framework these dots sit on top of. Carried over from
dots-wm's `HYDE-UPDATE.md` before that repo was abandoned (2026-08-08); trimmed to the
update itself, since the migration it was written for is done.

## What HyDE is to this repo

GUI hosts hard-depend on it: `hypr/hyprland.conf` sources
`~/.local/share/hyde/hyprland.conf`, which defines `$mainMod` and the framework vars.
Without it a GUI host dies with `source globbing error` + `invalid mod $mainMod`. That
file is **generated**, not tracked here — see README's "HyDE dependency".

## Should an old HyDE be updated?

Yes, once the host's dots are settled — an old HyDE paired with a current Arch Hyprland
is a known-bad mix, and it fails *silently*. Symptoms actually observed on wm (HyDE from
April 2025):

- ships the pre-0.45 `layerrule = blur,waybar` form, which current Hyprland rejects —
  HyDE wraps the source in `hyprlang noerror true`, so nothing is printed;
- hard-sources `hypr/themes/{theme,colors,wallbash}.conf`, which newer HyDE generates
  itself — missing them, Hyprland falls back to compositor defaults (border 1,
  rounding 0, `gaps_out` 20, no blur);
- `animations/theme.conf` is a `source = ./HyDE.conf` stub where `HyDE.conf` is a
  newer-HyDE artifact that does not exist there.

Upstream has since shipped config fixes for Hyprland 0.53 (windowrule overhaul), 0.54
(togglesplit binds) and 0.55 (config breaking changes). A 2025 HyDE predates all three.

Because of that old-HyDE behaviour, the **wm overlay tracks
`wm/.config/hypr/themes/{colors,theme,wallbash}.conf` and
`wm/.config/hypr/animations/theme.conf`** (force-added past the `**/hypr/themes/`
gitignore) — wm's HyDE hard-sources the former and never generates the `HyDE.conf` the
`gui` animations stub points at. Theme switches on wm write *through* those symlinks and
dirty the repo — expected; fl works the same way. **When wm's HyDE is finally updated,
delete all four from the overlay** (newer HyDE generates its own) and let
`reconcile-hyde.sh` sort out the rest.

**Do it as its own change** — never in the same sitting as a dots migration, or a single
symptom is unattributable.

## Can it be reverted? Only partially

`~/HyDE/Scripts/install.sh` overwrites `~/.config/hypr/*`, **replaces stow symlinks with
real files**, backs the old configs up to `~/.config/cfg_backups`, and installs/upgrades
packages.

- Recoverable: the **config layer** — dots are git-tracked, and
  `./bin/reconcile-hyde.sh --relink <host>` re-stows the repo versions (backing severed
  files up to a timestamped dir).
- **Not** recoverable: packages it upgraded, and HyDE's generated state
  (`~/.local/share/hyde/*`, `hyde/themes/`, wallpapers) — overwritten in place.
- There are **no system snapshots** on these machines (no timeshift, no btrfs
  `/.snapshots`), so there is no whole-system rollback.

A real undo therefore requires the backup in step 1. It is not optional.

## Procedure

1. **Back up — this is the only revert path.**
   ```fish
   tar czf ~/hyde-pre-update-(date +%F).tgz -C ~ .local/share/hyde .config/hypr .config/waybar
   pacman -Qe > ~/pkgs-pre-update.txt
   ```
2. **Update** (clone HyDE first if `~/HyDE` is absent):
   ```fish
   ~/HyDE/Scripts/install.sh     # -r restore mode overwrites ~/.config/hypr/*
   ```
3. **Reconcile the dots** — HyDE has just severed the stow symlinks:
   ```fish
   cd ~/.dots
   git commit -am wip                    # so reconcile choices stay reviewable
   ./bin/reconcile-hyde.sh <host>        # report only, safe
   ./bin/reconcile-hyde.sh -i <host>     # interactive: keep/take/merge per file
   #   or: ./bin/reconcile-hyde.sh --relink <host>   # repo versions win, re-stow
   ```
   Note `SUBTREES` in that script covers `.config/hypr` and `.config/waybar` only.
4. **Disable HyDE's own bar** (one-time; gui's exec-once launches the custom cava rig):
   ```fish
   systemctl --user stop hyde-(echo $XDG_SESSION_DESKTOP)-bar.service
   systemctl --user mask hyde-(echo $XDG_SESSION_DESKTOP)-bar.service
   ```
5. **Verify — `hyprctl configerrors` is not enough.** It returns empty even for a missing
   `source =`, which is what hid every bug above. Check the log and the `set:` flag:
   ```fish
   grep -cE 'globbing error|Error parsing gradient' /run/user/1000/hypr/*/hyprland.log
   hyprctl getoption decoration:rounding   # set: false = nothing ever assigned it
   ```
   Then review `git -C ~/.dots status` after the reconcile.

6. **Check the keybind scripts still exist — this is the one that bites.** 24 binds in
   `hypr/keybindings.conf` `exec` scripts out of HyDE's `$scrPath`, which the repo does not
   define or ship. When HyDE renames or drops one, the bind stays valid, Hyprland logs
   nothing, and the key simply stops doing anything. (This is how the 2026-07-20 lw clash
   presented: "no keybinds, no errors".) `dontkillsteam.sh` is a known upstream
   deprecation, and it is bound to **Super+Q and Alt+F4** — i.e. closing windows.
   ```fish
   set scr (grep -oP '(?<=\$scrPath\s?=\s?).*' ~/.local/share/hyde/hyprland.conf \
            | head -1 | string trim | string replace '$HOME' $HOME)
   echo "scrPath = $scr"
   for s in (grep -hoE '\$scrPath/[A-Za-z0-9._-]+' ~/.config/hypr/*.conf \
             | string replace '$scrPath/' '' | sort -u)
       test -e "$scr/$s"; or echo "MISSING: $s"
   end
   ```
   Anything listed MISSING needs its bind repointed at the current script name in
   `gui/.config/hypr/keybindings.conf` — that is a dots fix, not a HyDE one.

## Reverting

Partial only: `./bin/reconcile-hyde.sh --relink <host>` plus `git restore` bring back the
config layer, and `~/.config/cfg_backups` holds HyDE's own pre-update copies. Packages and
`~/.local/share/hyde/*` come back only from the step-1 tarball.