# [Feature] `omarchy theme from-wallpaper` — generate a theme's colors.toml from a wallpaper image

**Type:** Feature request · **Area:** theming (`bin/omarchy-theme-*`) · **Suggested labels:** `enhancement`, `theming`

## Summary

Add a command that builds a valid Omarchy theme out of an arbitrary image:

```bash
omarchy theme from-wallpaper ~/Pictures/wall.jpg          # create theme, print name
omarchy theme from-wallpaper ~/Pictures/wall.jpg --apply  # create and set it
```

It would extract a palette from the image, derive the full `colors.toml` schema (`mode`, `accent`/`selection`/`muted`, the four background and four foreground steps, the 8 base colors: `red yellow orange green cyan blue magenta brown`), write it to a custom theme dir under `~/.config/omarchy/themes/<name>/`, and reuse the existing `omarchy theme set` pipeline unchanged. Existing hand-picked themes are untouched.

## Why

- Omarchy's theming stack is already template-driven end to end (`default/themed/*.tpl`, `omarchy-theme-set-templates`, shell hot-reload). The single missing entry point is "make a theme from this wallpaper" — the highest-"wow"-per-line-of-code feature a theming engine can offer, and the most-asked theming question after "how do I add a theme".
- It composes with what exists: the generated theme is a normal theme, so `omarchy theme set`, the theme switcher, `omarchy theme bg-set` and user templates under `~/.config/omarchy/themed/` all keep working with zero changes.
- This is not a cold call: **#92** ("Dynamic color schemes based on wallpaper") explored exactly this idea, and the discussion closed with a clear maintainer direction — matugen-based generation, treated as "a theme in itself", with the existing hand-picked themes kept — but no follow-up ever landed (no matugen anywhere in the current tree, no generated theme in `omarchy theme list`). This issue proposes picking that thread up as a first-class command.
- Demand exists in the wild: the community package [omarchy-auto-theme](https://github.com/AccursedGalaxy/omarchy-auto-theme) already does wallpaper-based theming via matugen as a third-party add-on; upstreaming the generation step as a CLI command would give that whole category a supported foundation.

## Reference implementation (design inspiration only)

[Nisfeight8/Nisfere](https://github.com/Nisfeight8/Nisfere) builds its whole shell around live theming: a Python daemon extracts colors from the current wallpaper (`daemon/services/nisfere_chroma.py`) and renders them into every config via templates. **Nisfere has no license, so no code can be taken** — but the feature itself is a small, well-understood problem: k-means or median-cut quantization over a downsampled image, then schema mapping. Any implementation (Pillow/numpy one-off, or a tiny Rust helper) is fine; the point is the integration seam, not the algorithm.

## Proposed implementation

- New bin `omarchy-theme-colors-from-wallpaper <image> [theme-dir]`, sibling of the existing `omarchy-theme-colors-from-alacritty` (which already establishes the "derive colors.toml from a source" pattern: skip-if-exists, schema-complete output).
- Palette extraction via **matugen** (Rust, Material You-style quantization from an image), following the direction expressed in #92; a matugen template config ships alongside the bin to map matugen's output onto the Omarchy `colors.toml` keys (accent from the dominant tone, background/foreground steps from luminance-mapped neutrals with WCAG AA contrast checks, base colors from the remaining tones with a stock-ramp fallback when the image lacks hue diversity).
- Dependency question for maintainers: matugen as a new (optional) dependency vs a dependency-free ImageMagick fallback (`magick -resize ... -colors 8 -unique-colors txt:`) — happy to implement whichever fits the project's dependency budget; the schema-mapping bin is identical in both cases.
- Router entry `omarchy theme from-wallpaper <image> [--apply] [--name <name>]` in `bin/omarchy` (group `theme`): default name `wallpaper-<basename>`; refuses to overwrite an existing theme without `--force`.
- Derivation rules documented in `docs/theming.md`.

## Acceptance criteria

- [ ] `omarchy theme from-wallpaper <img> --apply` on a fresh install produces a theme where every themed target updates (shell, terminals, VS Code, hyprland, browsers config) — identical coverage to a stock theme.
- [ ] Generated `colors.toml` validates against the same schema checks stock themes pass (all keys present, valid hex).
- [ ] Very dark and very light wallpapers both produce readable themes (`mode` chosen accordingly, contrast-checked foreground).
- [ ] `--apply` also sets the wallpaper as background (composable with `omarchy theme bg-set` semantics).
- [ ] Documented in the manual: "creating a theme from an image".

## Out of scope

- Auto-switching themes when the wallpaper changes on its own (can be a hook recipe later: `omarchy hook install background-set`).
- Live chroma re-extraction on every wallpaper change inside the shell process.

## Credits

Feature concept popularized by the Nisfere shell's wallpaper-driven theming.