# Backgrounds added to a custom theme's `backgrounds/` don't appear in the wallpaper picker until the theme is re-applied

## Summary

Wallpaper files dropped into a **custom (user-created) theme's** `backgrounds/`
directory do not show up in the background switcher (`omarchy theme bg
switcher` / the wallpaper picker in the menu). They only appear after
re-running `omarchy theme set <theme>`.

For comparison, the documented "additional user backgrounds" location
(`~/.config/omarchy/backgrounds/<theme-slug>/`) works live — the picker picks
up files added there immediately. So the behavior differs between the two
locations, and the one that *feels* natural (the theme's own `backgrounds/`
folder) silently doesn't work.

## Environment

- Omarchy version: `4.0.3-1`
- Theme: `Walblack` (custom user theme, hand-written — not installed via
  `omarchy theme install`)
- Theme location: `~/.config/omarchy/themes/walblack/`

## Steps to reproduce

1. Have a custom theme applied, e.g. `omarchy theme set walblack`
2. Add a new wallpaper file to the theme's backgrounds dir:

   ```bash
   cp /path/to/new-wallpaper.jpg ~/.config/omarchy/themes/walblack/backgrounds/
   ```

3. Open the wallpaper picker (`omarchy theme bg switcher`) or run
   `omarchy theme bg next`

## Actual behavior

The new wallpaper does not appear in the picker. `omarchy theme bg next`
cycles only through the old set of wallpapers.

## Root cause (from reading the scripts)

`omarchy-theme-bg-next` and `omarchy-theme-bg-switcher` read wallpapers from
a **snapshot** taken at theme-apply time:

```
~/.local/state/omarchy/current/theme/backgrounds/
```

...not from the theme's live directory
(`~/.config/omarchy/themes/<slug>/backgrounds/`). The snapshot is only
refreshed when `omarchy theme set` runs. Files added to the theme's
`backgrounds/` after the last `theme set` are therefore invisible to both
commands until the theme is re-applied.

The state dir also mixes sources: it contains both the theme's own
backgrounds and any user backgrounds from `~/.config/omarchy/backgrounds/<slug>/`
copied in at apply time, which makes the live-vs-snapshot difference even
harder to notice.

## Expected behavior

One of:

- The picker and `bg next` also read the theme's **live** `backgrounds/`
  directory (in addition to the state snapshot), so newly added wallpapers
  appear without any extra step; or
- This is intentional, but it should be documented in the theming docs that
  custom theme `backgrounds/` changes require re-running
  `omarchy theme set <theme>` to be picked up (the current docs only mention
  running `theme set` "when done with the theme", which reads as a one-time
  finalization step, not a required re-sync).

## Workaround

Re-apply the theme after adding wallpapers to the theme's `backgrounds/`:

```bash
omarchy theme set walblack
```

or use the per-theme user backgrounds folder, which the picker reads live:

```bash
mkdir -p ~/.config/omarchy/backgrounds/walblack/
cp /path/to/new-wallpaper.jpg ~/.config/omarchy/backgrounds/walblack/
```

## Related issues (possibly)

- #8594 — `omarchy theme bg next` never advances when
  `~/.config/omarchy/backgrounds/<theme>` is a symlink
- #7116 — Applying a theme with no `backgrounds/` blanks the wallpaper and
  leaves a dangling symlink
- #8508 — Theme backgrounds can cycle forward but not backward

Happy to turn this into a proper GitHub issue with full `omarchy debug`
output if maintainers confirm the behavior is unintended.