docs: add theme persistence, wallp-owned state dir to spec

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 58 insertions, 27 deletions

diff --git a/docs/superpowers/specs/2026-06-11-wallp-merge-design.md b/docs/superpowers/specs/2026-06-11-wallp-merge-design.md
index 5f23772..b1a85b3 100644
--- a/docs/superpowers/specs/2026-06-11-wallp-merge-design.md
+++ b/docs/superpowers/specs/2026-06-11-wallp-merge-design.md
@@ -80,26 +80,49 @@ An example conf is shipped in the repo (`wallp.conf.example`).
 
 ## State Files
 
-Runtime pointers (volatile, in `~/.cache`, reset on reboot):
+Persistent state (wallp-owned, `~/.config/wallp/`, survives reboot):
 
-- `~/.cache/wal/wal`  — H wallpaper path. Read by pywal and apps.
-- `~/.cache/wal/wal2` — V wallpaper path.
-- `~/.cache/wal/wpaper` — symlink to current H image (maintained by wallp).
+- `~/.config/wallp/wall_h` — H wallpaper path.
+- `~/.config/wallp/wall_v` — V wallpaper path.
+- `~/.config/wallp/theme`  — last-used theme name.
+- `~/.config/wallp/wallp.conf` — config (see Config section).
 
-Persistent pointers (survive reboot, in `~/.config`):
-
-- `~/.config/wal/wal`  — H wallpaper path.
-- `~/.config/wal/wal2` — V wallpaper path.
-
-PID tracking (runtime only, meaningless after reboot):
+Runtime state (volatile, reset on reboot):
 
+- `~/.cache/wal/wpaper` — symlink to current H image. **Kept** because it has
+  external consumers (rofi themes under `~/.config/rofi/darknix/*.rasi`). wallp
+  maintains it.
 - `~/.cache/wallp/H.pid` — swaybg PID for horizontal output.
 - `~/.cache/wallp/V.pid` — swaybg PID for vertical output.
 
-wallp writes **all** pointer files directly (cache + config) on set and restore.
-This moves persistence out of `wal.sh` and into wallp. `wal.sh` is reduced to its
-theme-app glue only (dunst symlink+restart, kitty symlink); it loses the
-wal/wal2/wpaper copy logic. `wal.sh` remains the wal `-o` hook for future use.
+Dropped (no external consumer; confirmed via grep over `~/bin` and `~/.config`):
+
+- `~/.cache/wal/wal`, `~/.cache/wal/wal2` — only the replaced scripts wrote
+  these; nothing else reads them.
+- `~/.config/wal/wal`, `~/.config/wal/wal2` — superseded by `~/.config/wallp/`.
+
+wallp owns all its persistence directly in `~/.config/wallp/`. This moves
+persistence out of `wal.sh` and into wallp. `wal.sh` is reduced to its theme-app
+glue only (dunst symlink+restart, kitty symlink); it loses the wal/wal2/wpaper
+copy logic. `wal.sh` remains the wal `-o` hook for future use.
+
+Note: `~/.cache/wal/colors.json` is pywal-native (written by `wal` itself, read
+by `pywal_sublime.py`); not touched by wallp.
+
+## Theme Persistence
+
+The last-used theme is persisted to `~/.config/wallp/theme` and survives reboot.
+Conf `THEME` is only the first-run default. Precedence on every action:
+
+1. `--theme <name>` flag → use it.
+2. else persisted `~/.config/wallp/theme` (if present).
+3. else conf `THEME`.
+4. else built-in `sexy-splurge`.
+
+Whatever theme is resolved gets persisted to `~/.config/wallp/theme`. This means
+once a theme is set it sticks (for both `--set` and `--restore`) until changed
+via `--theme`. `--restore` thus brings back the last-used theme, not the conf
+default.
 
 ## Set Flow
 
@@ -110,13 +133,14 @@ For each chosen output (H and/or V):
 2. Selective kill: read `<X>.pid`; if the PID is alive, `kill` it. The other
    output's swaybg is left untouched.
 3. `swaybg -o <OUTPUT> -i <file> -m fill &`; save the new PID to `<X>.pid`.
-4. Write the pointer to cache (`wal`/`wal2`) and config (`wal`/`wal2`).
+4. Persist the path to `~/.config/wallp/wall_h` (H) or `wall_v` (V).
 
 After all chosen outputs are done:
 
-5. Update `~/.cache/wal/wpaper` symlink → current H image.
-6. Run `wal --backend colorz -nq --theme <THEME> -o ~/bin/wal.sh`.
-7. `notify-send` color-theme update.
+5. Update `~/.cache/wal/wpaper` symlink → current H image (for rofi).
+6. Resolve theme (see Theme Persistence), persist to `~/.config/wallp/theme`.
+7. Run `wal --backend colorz -nq --theme <THEME> -o ~/bin/wal.sh`.
+8. `notify-send` color-theme update.
 
 qarma selection flow (`--set`, display present, no args):
 
@@ -129,16 +153,17 @@ qarma selection flow (`--set`, display present, no args):
 
 For each output H/V:
 
-1. If the persistent pointer (`~/.config/wal/wal` for H, `wal2` for V) exists →
-   read the path, selective-kill that output's old PID, `swaybg`, save PID, and
-   sync the pointer to `~/.cache/wal/`.
+1. If the persistent pointer (`~/.config/wallp/wall_h` for H, `wall_v` for V)
+   exists → read the path, selective-kill that output's old PID, `swaybg`,
+   save PID.
 2. If no persistent pointer for that output → use `DEFAULT_H`/`DEFAULT_V` from
-   conf, write both pointers (cache + config), swaybg, save PID.
+   conf, persist it (`wall_h`/`wall_v`), swaybg, save PID.
 
 After both outputs:
 
 3. Update `wpaper` symlink → H image.
-4. Run wal theme + notify (same as set steps 6-7).
+4. Resolve theme (persisted theme wins, see Theme Persistence), persist it,
+   run wal theme + notify (same as set steps 7-8).
 
 No display required. Replaces `qar-lastwall.sh`. Intended for session-start
 autostart.
@@ -167,8 +192,10 @@ The script is side-effecting (swaybg, wal, filesystem). Strategy:
 - Assertions:
   - Conf-missing path generates the template and changes no wallpaper.
   - Missing required key hard-errors.
-  - `--set V=<file>` writes V pointers (cache + config) and leaves `H.pid`
+  - `--set V=<file>` writes `~/.config/wallp/wall_v` and leaves `H.pid`
     untouched (partial update does not blank H).
+  - Theme persistence: `--theme X` writes `~/.config/wallp/theme`; a later
+    no-flag run resolves X (persisted wins over conf THEME).
   - Selective kill targets only the changed output's PID.
   - Restore falls back to `DEFAULT_*` when no persistent pointer exists.
   - `~` in conf paths expands to `$HOME`.
@@ -176,9 +203,13 @@ The script is side-effecting (swaybg, wal, filesystem). Strategy:
 
 ## Migration Notes
 
-- `wal.sh` lines 16-27 (wal/wal2/wpaper copy + symlink) move into wallp; remove
-  them from `wal.sh`, keep dunst + kitty glue.
+- `wal.sh` lines 16-27 (wal/wal2/wpaper copy + symlink) — remove the wal/wal2
+  copy lines (16,19,22-23) entirely; the `wpaper` symlink moves into wallp.
+  Keep dunst + kitty glue (lines 7,13). `wal.sh` stays the wal `-o` hook.
 - Old `qar-lastwall.sh` read `~/.config/wal/*`; old `multiwal.sh` wrote
-  `~/.cache/wal/*` — this mismatch bug is resolved: wallp writes both.
+  `~/.cache/wal/*` — mismatch bug resolved: wallp uses a single owned location
+  `~/.config/wallp/`.
 - Old default-wallpaper paths had a literal quoted `~` (swaybg would not expand)
   — fixed via `~`→`$HOME` expansion on conf load.
+- `~/.cache/wal/wpaper` retained — consumed by `~/.config/rofi/darknix/*.rasi`.
+- `~/.cache/wal/wal` + `wal2` dropped — no external consumer (grep-verified).