Move current theme state to local state

docs/file-layout.md

@@ -42,6 +42,11 @@ Three layers populate `$HOME`:
 `/etc/skel` only fires at user creation. Existing users picking up new
 defaults must use the resync command.
 
+Current generated theme state lives under
+`~/.local/state/omarchy/current/`. Keep `~/.config/omarchy/` for files a user
+may intentionally version in a dotfile manager, such as user themes, hooks,
+shell layout, plugin sources, and themed template overrides.
+
 ## Build-time map (repo → installed paths)
 
 ```
@@ -284,4 +289,6 @@ return to the packaged default.
 | Noninteractive root fix for existing installs | `migrations/system/<unix-timestamp>.sh` |
 | User/session fix for existing installs | `migrations/user/<unix-timestamp>.sh` |
 | User-facing `omarchy-*` command | `bin/omarchy-<group>-<verb>` — see `GROUP_DESCRIPTIONS` in `bin/omarchy` |
-| New theme | `themes/<name>/` (+ matching templates under `default/themed/` if they need theme colors) |
+| New stock theme | `themes/<name>/` (+ matching templates under `default/themed/` if they need theme colors) |
+| User-installed theme | `~/.config/omarchy/themes/<name>/` |
+| Generated current theme/background state | `~/.local/state/omarchy/current/` |

docs/theming.md

@@ -1,22 +1,23 @@
 # Omarchy theming
 
-Omarchy themes live under `themes/<name>/` in the source tree, with optional
-user themes under `~/.config/omarchy/themes/<name>/`. A theme normally starts
-with a `colors.toml`; Omarchy generates the rest of the theme files from
+Omarchy themes live under `themes/<name>/` in the source tree (installed at
+`/usr/share/omarchy/themes/<name>/`), with optional user themes under
+`~/.config/omarchy/themes/<name>/`. A theme normally starts with a
+`colors.toml`; Omarchy generates the active theme files from
 `default/themed/*.tpl` when `omarchy-theme-set <name>` runs.
 
 ## Theme activation flow
 
 `omarchy-theme-set <name>` builds a clean staging directory at
-`~/.config/omarchy/current/next-theme`:
+`~/.local/state/omarchy/current/next-theme`:
 
 1. Copy the first-party theme from `themes/<name>/`.
 2. Overlay any user theme files from `~/.config/omarchy/themes/<name>/`.
 3. If needed, generate `colors.toml` from `alacritty.toml`.
 4. Run `omarchy-theme-set-templates` to render templates into the staging
    theme.
-5. Move the staging theme into `~/.config/omarchy/current/theme` and notify the
-   running shell.
+5. Move the staging theme into `~/.local/state/omarchy/current/theme`, write
+   `~/.local/state/omarchy/current/theme.name`, and notify the running shell.
 
 Template rendering only happens when the staged theme has `colors.toml`.
 Existing files are never overwritten by a template, so a hand-written

docs/update-process.md

@@ -25,6 +25,7 @@ The design goal is:
 | `${XDG_RUNTIME_DIR:-/tmp}/omarchy-update.lock` | user | Prevent overlapping update runs. Owned by `omarchy-update`; compatibility wrappers inherit/respect it. |
 | `/tmp/omarchy-update.log` | user | Transcript of `omarchy update`, used by `omarchy-update-analyze-logs`. |
 | `~/.local/state/omarchy/updates/` | user | Update-check state for the shell widget (`packages`, `aur`, `available`, `checked-at`, `error`). |
+| `~/.local/state/omarchy/current/` | user | Generated active theme, selected theme name, and current background symlink. |
 | `/var/lib/omarchy/migrations/system/` | root | System migration markers. |
 | `~/.local/state/omarchy/migrations/user/` | user | User migration markers. |
 | `~/.local/state/omarchy/reboot-required` | user | Optional reboot marker checked by `omarchy-update-restart`. |