Make new wallpapers in a custom theme's backgrounds folder show up in the picker
Read omarchy-theme-bg-switcher, omarchy-theme-bg-next, omarchy-theme-set, omarchy-theme-refresh and omarchy-menu-images on this 4.0.4-1 workstation. The cause holds: both commands read ~/.local/state/omarchy/current/theme/backgrounds (a copy staged by omarchy-theme-set) and ~/.config/omarchy/backgrounds/<theme.name> live. Unlike the issue's claim, 4.0.4-1 does not copy the user folder into the state copy, and the record already says so. The picker's row cache keys on directory mtime, so a file added to the user folder invalidates it. The symlink warning holds: bg-set stores realpath, bg-next lists paths through the symlinked dir, so the index never matches and it always picks the first image. Two defects in the fix: omarchy theme bg switcher only prints the chosen path (the menu entry and Background.qml pipe it to omarchy-theme-bg-set), so selecting in it from a terminal sets nothing, and the second block used $theme defined only in the first block. Rewrote the fix to use Super+Ctrl+Space (bound in default/hypr/bindings/utilities.lua line 17) or the full one-liner, and made each block self-contained. Nothing was run that changes state.
Symptom
I copied new images into ~/.config/omarchy/themes/<my-theme>/backgrounds/. The background switcher (Super+Ctrl+Space, omarchy theme bg switcher) does not show them, and omarchy theme bg next cycles only through the old set. They appear only after I run omarchy theme set <my-theme> again.
Cause
omarchy-theme-bg-switcher and omarchy-theme-bg-next read two places. One is ~/.local/state/omarchy/current/theme/backgrounds/, a copy made when the theme was applied. The other is ~/.config/omarchy/backgrounds/<theme-name>/, which is read live. The theme's own backgrounds/ folder reaches the state copy only when omarchy-theme-set restages the theme. Files added later are invisible until then.
Fix
Use the per-theme user folder, which both the switcher and omarchy theme bg next read live:
theme=$(cat ~/.local/state/omarchy/current/theme.name)
mkdir -p ~/.config/omarchy/backgrounds/"$theme"
cp /path/to/new-wallpaper.jpg ~/.config/omarchy/backgrounds/"$theme"/
Then open the picker with Super+Ctrl+Space. From a terminal, omarchy theme bg switcher only prints the path you pick, so pass that on to set it:
bg=$(omarchy theme bg switcher) && [[ -n $bg ]] && omarchy theme bg set "$bg"
Or, for a theme you wrote yourself under ~/.config/omarchy/themes/, keep the files in the theme folder and restage the theme after adding them. omarchy-theme-refresh re-applies the current theme without changing the wallpaper you have now. Like any theme change, it also reloads terminals and re-themes apps:
theme=$(cat ~/.local/state/omarchy/current/theme.name)
cp /path/to/new-wallpaper.jpg ~/.config/omarchy/themes/"$theme"/backgrounds/
omarchy-theme-refresh
Do not make ~/.config/omarchy/backgrounds/<theme> itself a symlink, because omarchy theme bg next then never advances.
Verify
ls ~/.local/state/omarchy/current/theme/backgrounds/ ~/.config/omarchy/backgrounds/$(cat ~/.local/state/omarchy/current/theme.name)/
The new file is in one of the two lists and appears in the switcher.