docs: wallp merge implementation plan

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

1 files changed, 1166 insertions, 0 deletions

diff --git a/docs/superpowers/plans/2026-06-11-wallp-merge.md b/docs/superpowers/plans/2026-06-11-wallp-merge.md
new file mode 100644
index 0000000..3b17c88
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-11-wallp-merge.md
@@ -0,0 +1,1166 @@
+# wallp Merge Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Merge `multiwal.sh` (interactive setter) and `qar-lastwall.sh` (restorer) into one flag-driven bash script `wallp` with per-output partial updates, theme persistence, and a config file.
+
+**Architecture:** Single bash script `wallp`. Pure logic (conf parse, arg parse, `~` expansion, output mapping, theme resolution) lives in sourceable functions. Side-effecting actions (swaybg, wal, qarma, notify-send, filesystem writes) are isolated in thin functions. The script runs `main "$@"` only when executed directly, so a plain-bash test harness can source it and unit-test the pure functions with PATH stubs and a temp `$HOME`. Persistence is wallp-owned under `~/.config/wallp/`; a `~/.cache/wal/wpaper` symlink is maintained for rofi.
+
+**Tech Stack:** bash, swaybg, pywal (`wal`), qarma, notify-send. Tests: plain bash harness (no bats/shellcheck — not installed on this Slackware host), PATH stubs, temp `$HOME`.
+
+---
+
+## Conventions
+
+- All tests live in `tests/`. The harness `tests/run.sh` sources `wallp`, sets `HOME` to a temp dir, prepends a stub dir to `PATH`, and runs `test_*` functions, printing PASS/FAIL and exiting non-zero on any failure.
+- `wallp` ends with:
+  ```bash
+  if [ "${BASH_SOURCE[0]}" = "$0" ]; then main "$@"; fi
+  ```
+  so sourcing it for tests does not run `main`.
+- Every function reads paths via variables seeded from `$HOME` at call time (no hardcoded `/home/danix`), so tests relocating `$HOME` work.
+- Commit after each task.
+
+## File Structure
+
+- Create: `wallp` — the merged script (all logic + `main`).
+- Create: `wallp.conf.example` — shipped example config.
+- Create: `tests/run.sh` — bash test harness + assertions, sources `wallp`.
+- Create: `tests/stubs/` — stub executables (`swaybg`, `wal`, `qarma`, `notify-send`) created by the harness at runtime (not committed; harness writes them to a temp dir).
+- Modify: `/home/danix/bin/wal.sh` — remove wal/wal2 copy lines + wpaper symlink (done late, after wallp owns it). Out of repo; handled in final task with explicit diff.
+- Delete (after wallp verified): `multiwal.sh`, `qar-lastwall.sh` — final task.
+
+---
+
+## Task 1: Test harness skeleton
+
+**Files:**
+- Create: `tests/run.sh`
+- Create: `wallp` (stub: just a shebang + sourcing guard so harness can source it)
+
+- [ ] **Step 1: Create minimal sourceable `wallp`**
+
+Create `wallp`:
+
+```bash
+#!/bin/bash
+# wallp — unified wallpaper manager. See docs/superpowers/specs/.
+
+set -u
+
+main() {
+  return 0
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then main "$@"; fi
+```
+
+- [ ] **Step 2: Write the harness with one trivial test**
+
+Create `tests/run.sh`:
+
+```bash
+#!/bin/bash
+# Plain-bash test harness for wallp. No bats dependency.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PASS=0
+FAIL=0
+
+setup() {
+  TMP_HOME="$(mktemp -d)"
+  STUB_DIR="$TMP_HOME/stubs"
+  mkdir -p "$STUB_DIR"
+  export HOME="$TMP_HOME"
+  export PATH="$STUB_DIR:$PATH"
+  # default stubs: record calls to $TMP_HOME/calls.log, succeed
+  for bin in swaybg wal qarma notify-send pkill kill; do
+    cat > "$STUB_DIR/$bin" <<EOF
+#!/bin/bash
+echo "$bin \$*" >> "$TMP_HOME/calls.log"
+exit 0
+EOF
+    chmod +x "$STUB_DIR/$bin"
+  done
+}
+
+teardown() {
+  rm -rf "$TMP_HOME"
+}
+
+assert_eq() { # expected actual msg
+  if [ "$1" = "$2" ]; then PASS=$((PASS+1));
+  else FAIL=$((FAIL+1)); echo "FAIL: $3 (expected '$1' got '$2')"; fi
+}
+assert_file() { # path msg
+  if [ -f "$1" ]; then PASS=$((PASS+1));
+  else FAIL=$((FAIL+1)); echo "FAIL: $2 (missing file $1)"; fi
+}
+assert_no_file() { # path msg
+  if [ ! -e "$1" ]; then PASS=$((PASS+1));
+  else FAIL=$((FAIL+1)); echo "FAIL: $2 (file exists $1)"; fi
+}
+assert_contains() { # haystack needle msg
+  case "$1" in *"$2"*) PASS=$((PASS+1));; *) FAIL=$((FAIL+1)); echo "FAIL: $3 (no '$2' in '$1')";; esac
+}
+
+run_all() {
+  for t in $(declare -F | awk '{print $3}' | grep '^test_'); do
+    setup
+    source "$SCRIPT_DIR/wallp"
+    "$t"
+    teardown
+  done
+  echo "PASS=$PASS FAIL=$FAIL"
+  [ "$FAIL" -eq 0 ]
+}
+
+test_harness_self() {
+  assert_eq "x" "x" "harness sanity"
+}
+
+run_all
+```
+
+- [ ] **Step 3: Run harness, verify it passes**
+
+Run: `bash tests/run.sh`
+Expected: `PASS=1 FAIL=0`, exit 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "test: bash harness skeleton + sourceable wallp stub"
+```
+
+---
+
+## Task 2: `~` expansion helper
+
+**Files:**
+- Modify: `wallp` (add `expand_tilde`)
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing test**
+
+Add to `tests/run.sh` before `run_all`:
+
+```bash
+test_expand_tilde_home() {
+  assert_eq "$HOME/pics/a.png" "$(expand_tilde '~/pics/a.png')" "leading tilde expands"
+}
+test_expand_tilde_noop() {
+  assert_eq "/abs/b.png" "$(expand_tilde '/abs/b.png')" "absolute path untouched"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `expand_tilde: command not found` / failed asserts.
+
+- [ ] **Step 3: Implement**
+
+Add to `wallp` above `main`:
+
+```bash
+# Expand a leading ~ or ~/ to $HOME. Leaves other paths unchanged.
+expand_tilde() {
+  case "$1" in
+    "~") printf '%s\n' "$HOME" ;;
+    "~/"*) printf '%s\n' "$HOME/${1#\~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: PASS count up, `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: expand_tilde helper"
+```
+
+---
+
+## Task 3: Config parsing
+
+Parses `key=value` lines (ignore blanks + `#`), expands `~` in path values, sets globals `CONF_THEME CONF_OUTPUT_H CONF_OUTPUT_V CONF_DEFAULT_H CONF_DEFAULT_V`.
+
+**Files:**
+- Modify: `wallp` (add `parse_conf`)
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing test**
+
+Add to `tests/run.sh`:
+
+```bash
+test_parse_conf_reads_keys() {
+  conf="$HOME/c.conf"
+  printf '%s\n' \
+    '# comment' '' \
+    'THEME=mytheme' \
+    'OUTPUT_H=DP-1' \
+    'OUTPUT_V=DP-3' \
+    'DEFAULT_H=~/p/h.png' \
+    'DEFAULT_V=/abs/v.png' > "$conf"
+  parse_conf "$conf"
+  assert_eq "mytheme" "$CONF_THEME" "theme"
+  assert_eq "DP-1" "$CONF_OUTPUT_H" "output_h"
+  assert_eq "DP-3" "$CONF_OUTPUT_V" "output_v"
+  assert_eq "$HOME/p/h.png" "$CONF_DEFAULT_H" "default_h tilde expanded"
+  assert_eq "/abs/v.png" "$CONF_DEFAULT_V" "default_v abs"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `parse_conf: command not found`.
+
+- [ ] **Step 3: Implement**
+
+Add to `wallp`:
+
+```bash
+# Parse key=value conf into CONF_* globals. Ignores blanks and #-comments.
+# Expands ~ in DEFAULT_* path values. Does not validate (see require_conf_keys).
+CONF_THEME="" CONF_OUTPUT_H="" CONF_OUTPUT_V="" CONF_DEFAULT_H="" CONF_DEFAULT_V=""
+parse_conf() {
+  local file="$1" line key val
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in ''|'#'*) continue ;; esac
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      THEME)     CONF_THEME="$val" ;;
+      OUTPUT_H)  CONF_OUTPUT_H="$val" ;;
+      OUTPUT_V)  CONF_OUTPUT_V="$val" ;;
+      DEFAULT_H) CONF_DEFAULT_H="$(expand_tilde "$val")" ;;
+      DEFAULT_V) CONF_DEFAULT_V="$(expand_tilde "$val")" ;;
+    esac
+  done < "$file"
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: parse_conf key=value config loader"
+```
+
+---
+
+## Task 4: Conf bootstrap + required-key validation
+
+`load_conf` orchestrates: if conf missing → write template, message, signal "bootstrapped" (caller exits 0); else parse + validate required path/output keys (hard error). THEME falls back to `sexy-splurge` if empty.
+
+**Files:**
+- Modify: `wallp` (add `conf_path`, `write_conf_template`, `require_conf_keys`, `load_conf`)
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+Add to `tests/run.sh`:
+
+```bash
+test_load_conf_missing_bootstraps() {
+  out="$(load_conf 2>&1)"; rc=$?
+  assert_eq "10" "$rc" "missing conf returns rc 10 (bootstrapped)"
+  assert_file "$HOME/.config/wallp/wallp.conf" "template written"
+  assert_contains "$out" "fill it in" "user told to fill conf"
+}
+test_load_conf_missing_key_hard_errors() {
+  mkdir -p "$HOME/.config/wallp"
+  printf '%s\n' 'OUTPUT_H=DP-1' 'OUTPUT_V=DP-3' 'DEFAULT_H=/a.png' \
+    > "$HOME/.config/wallp/wallp.conf"   # DEFAULT_V missing
+  out="$(load_conf 2>&1)"; rc=$?
+  assert_eq "1" "$rc" "missing key rc 1"
+  assert_contains "$out" "DEFAULT_V" "names missing key"
+}
+test_load_conf_ok_theme_fallback() {
+  mkdir -p "$HOME/.config/wallp"
+  printf '%s\n' 'OUTPUT_H=DP-1' 'OUTPUT_V=DP-3' \
+    'DEFAULT_H=/a.png' 'DEFAULT_V=/b.png' \
+    > "$HOME/.config/wallp/wallp.conf"   # no THEME
+  load_conf; rc=$?
+  assert_eq "0" "$rc" "valid conf rc 0"
+  assert_eq "sexy-splurge" "$CONF_THEME" "theme fallback"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `load_conf: command not found`.
+
+- [ ] **Step 3: Implement**
+
+Add to `wallp`:
+
+```bash
+conf_path() { printf '%s\n' "$HOME/.config/wallp/wallp.conf"; }
+
+write_conf_template() {
+  local path; path="$(conf_path)"
+  mkdir -p "$(dirname "$path")"
+  cat > "$path" <<'EOF'
+# wallp config. Fill in real values, then re-run wallp.
+# THEME is optional (defaults to sexy-splurge).
+THEME=sexy-splurge
+# Physical output names (see: swaymsg -t get_outputs / wlr-randr)
+OUTPUT_H=DP-1
+OUTPUT_V=DP-3
+# Default wallpapers used by --restore when no saved state exists.
+DEFAULT_H=~/Pictures/wallpapers/SFW/horizontal.png
+DEFAULT_V=~/Pictures/wallpapers/SFW/vertical.png
+EOF
+}
+
+# Hard-error if any required path/output key is empty. Returns 1 on first miss.
+require_conf_keys() {
+  local k
+  for k in OUTPUT_H OUTPUT_V DEFAULT_H DEFAULT_V; do
+    local var="CONF_$k"
+    if [ -z "${!var}" ]; then
+      echo "wallp: required config key '$k' is missing or empty in $(conf_path)" >&2
+      return 1
+    fi
+  done
+  return 0
+}
+
+# Returns: 0 ok, 1 invalid conf, 10 bootstrapped (caller should exit 0).
+load_conf() {
+  local path; path="$(conf_path)"
+  if [ ! -f "$path" ]; then
+    write_conf_template
+    echo "wallp: generated config at $path — fill it in and re-run." >&2
+    command -v notify-send >/dev/null 2>&1 && \
+      notify-send -u normal "wallp" "Config generated at $path. Fill it in and re-run."
+    return 10
+  fi
+  parse_conf "$path"
+  [ -z "$CONF_THEME" ] && CONF_THEME="sexy-splurge"
+  require_conf_keys || return 1
+  return 0
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: conf bootstrap + required-key validation"
+```
+
+---
+
+## Task 5: Theme resolution + persistence
+
+`resolve_theme <flag_theme>` precedence: flag > persisted (`~/.config/wallp/theme`) > `CONF_THEME` > `sexy-splurge`. `persist_theme <name>` writes the file.
+
+**Files:**
+- Modify: `wallp` (add `theme_file`, `persist_theme`, `resolve_theme`)
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_resolve_theme_flag_wins() {
+  CONF_THEME="conf"; mkdir -p "$HOME/.config/wallp"
+  echo persisted > "$HOME/.config/wallp/theme"
+  assert_eq "flagged" "$(resolve_theme flagged)" "flag beats all"
+}
+test_resolve_theme_persisted_beats_conf() {
+  CONF_THEME="conf"; mkdir -p "$HOME/.config/wallp"
+  echo persisted > "$HOME/.config/wallp/theme"
+  assert_eq "persisted" "$(resolve_theme '')" "persisted beats conf"
+}
+test_resolve_theme_conf_when_no_persist() {
+  CONF_THEME="conf"
+  assert_eq "conf" "$(resolve_theme '')" "conf used"
+}
+test_persist_theme_writes() {
+  persist_theme "abc"
+  assert_eq "abc" "$(cat "$HOME/.config/wallp/theme")" "theme persisted"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — functions not defined.
+
+- [ ] **Step 3: Implement**
+
+```bash
+theme_file() { printf '%s\n' "$HOME/.config/wallp/theme"; }
+
+persist_theme() {
+  local f; f="$(theme_file)"
+  mkdir -p "$(dirname "$f")"
+  printf '%s\n' "$1" > "$f"
+}
+
+# Precedence: flag arg > persisted file > CONF_THEME > sexy-splurge.
+resolve_theme() {
+  local flag="$1" f; f="$(theme_file)"
+  if [ -n "$flag" ]; then printf '%s\n' "$flag"; return; fi
+  if [ -s "$f" ]; then head -n1 "$f"; return; fi
+  if [ -n "${CONF_THEME:-}" ]; then printf '%s\n' "$CONF_THEME"; return; fi
+  printf '%s\n' "sexy-splurge"
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: theme resolution + persistence"
+```
+
+---
+
+## Task 6: Logical→physical output mapping + persistence paths
+
+Map `H`/`V` to `CONF_OUTPUT_H`/`CONF_OUTPUT_V`; provide persistence-path and pid-path helpers.
+
+**Files:**
+- Modify: `wallp`
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_output_for_logical() {
+  CONF_OUTPUT_H="DP-1"; CONF_OUTPUT_V="DP-3"
+  assert_eq "DP-1" "$(output_for H)" "H maps"
+  assert_eq "DP-3" "$(output_for V)" "V maps"
+}
+test_wall_file_for() {
+  assert_eq "$HOME/.config/wallp/wall_h" "$(wall_file_for H)" "wall_h path"
+  assert_eq "$HOME/.config/wallp/wall_v" "$(wall_file_for V)" "wall_v path"
+}
+test_pid_file_for() {
+  assert_eq "$HOME/.cache/wallp/H.pid" "$(pid_file_for H)" "H pid path"
+  assert_eq "$HOME/.cache/wallp/V.pid" "$(pid_file_for V)" "V pid path"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — functions not defined.
+
+- [ ] **Step 3: Implement**
+
+```bash
+output_for() {
+  case "$1" in
+    H) printf '%s\n' "$CONF_OUTPUT_H" ;;
+    V) printf '%s\n' "$CONF_OUTPUT_V" ;;
+    *) echo "wallp: unknown logical output '$1'" >&2; return 1 ;;
+  esac
+}
+wall_file_for() {
+  case "$1" in
+    H) printf '%s\n' "$HOME/.config/wallp/wall_h" ;;
+    V) printf '%s\n' "$HOME/.config/wallp/wall_v" ;;
+  esac
+}
+pid_file_for() {
+  case "$1" in
+    H) printf '%s\n' "$HOME/.cache/wallp/H.pid" ;;
+    V) printf '%s\n' "$HOME/.cache/wallp/V.pid" ;;
+  esac
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: output mapping + state path helpers"
+```
+
+---
+
+## Task 7: `--set H=/V=` argument parsing
+
+`parse_set_args` consumes `H=<file>` / `V=<file>` tokens into associative-style globals `SET_H`/`SET_V`; rejects unknown tokens.
+
+**Files:**
+- Modify: `wallp`
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_parse_set_args_both() {
+  SET_H="" SET_V=""
+  parse_set_args "H=/a.png" "V=/b.png"
+  assert_eq "/a.png" "$SET_H" "H captured"
+  assert_eq "/b.png" "$SET_V" "V captured"
+}
+test_parse_set_args_partial() {
+  SET_H="" SET_V=""
+  parse_set_args "V=/only.png"
+  assert_eq "" "$SET_H" "H empty"
+  assert_eq "/only.png" "$SET_V" "V captured"
+}
+test_parse_set_args_tilde() {
+  SET_H="" SET_V=""
+  parse_set_args "H=~/x.png"
+  assert_eq "$HOME/x.png" "$SET_H" "H tilde expanded"
+}
+test_parse_set_args_unknown_rejected() {
+  SET_H="" SET_V=""
+  out="$(parse_set_args "Z=/bad.png" 2>&1)"; rc=$?
+  assert_eq "1" "$rc" "unknown token rc1"
+  assert_contains "$out" "Z=" "names bad token"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `parse_set_args: command not found`.
+
+- [ ] **Step 3: Implement**
+
+```bash
+SET_H="" SET_V=""
+parse_set_args() {
+  local tok
+  for tok in "$@"; do
+    case "$tok" in
+      H=*) SET_H="$(expand_tilde "${tok#H=}")" ;;
+      V=*) SET_V="$(expand_tilde "${tok#V=}")" ;;
+      *) echo "wallp: unknown --set argument '$tok' (expected H=<file> or V=<file>)" >&2; return 1 ;;
+    esac
+  done
+  return 0
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: parse --set H=/V= arguments"
+```
+
+---
+
+## Task 8: Apply a single wallpaper (selective kill + swaybg + persist)
+
+`apply_output <H|V> <file>`: validate file exists; selective-kill prior PID; launch swaybg; save new PID; persist path to `wall_h`/`wall_v`. Returns 1 (skip) on missing file without blanking.
+
+**Files:**
+- Modify: `wallp`
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_apply_output_missing_file_skips() {
+  CONF_OUTPUT_H="DP-1"
+  out="$(apply_output H "$HOME/nope.png" 2>&1)"; rc=$?
+  assert_eq "1" "$rc" "missing file rc1"
+  assert_no_file "$(pid_file_for H)" "no pid written on skip"
+}
+test_apply_output_sets_and_persists() {
+  CONF_OUTPUT_H="DP-1"
+  : > "$HOME/real.png"
+  apply_output H "$HOME/real.png"; rc=$?
+  assert_eq "0" "$rc" "apply ok"
+  assert_eq "$HOME/real.png" "$(cat "$(wall_file_for H)")" "path persisted"
+  assert_file "$(pid_file_for H)" "pid written"
+  assert_contains "$(cat "$HOME/calls.log")" "swaybg -o DP-1 -i $HOME/real.png" "swaybg launched"
+}
+test_apply_output_v_does_not_touch_h_pid() {
+  CONF_OUTPUT_H="DP-1" CONF_OUTPUT_V="DP-3"
+  mkdir -p "$HOME/.cache/wallp"; echo 99999 > "$(pid_file_for H)"
+  : > "$HOME/v.png"
+  apply_output V "$HOME/v.png"
+  assert_eq "99999" "$(cat "$(pid_file_for H)")" "H pid untouched on V update"
+}
+```
+
+Note: the harness `swaybg` stub exits 0 immediately, so `$!` is a real (already-exited) PID — fine for assertions. The `kill` stub records and exits 0.
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `apply_output: command not found`.
+
+- [ ] **Step 3: Implement**
+
+```bash
+# Kill the swaybg recorded for a logical output, if its PID is still alive.
+kill_output() {
+  local logical="$1" pf pid; pf="$(pid_file_for "$logical")"
+  [ -f "$pf" ] || return 0
+  pid="$(cat "$pf")"
+  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+    kill "$pid" 2>/dev/null
+  fi
+  rm -f "$pf"
+}
+
+# apply_output <H|V> <file>: set wallpaper for one output. rc1 = skipped.
+apply_output() {
+  local logical="$1" file="$2" output pf wf
+  if [ ! -f "$file" ]; then
+    echo "wallp: file not found, skipping $logical: $file" >&2
+    return 1
+  fi
+  output="$(output_for "$logical")" || return 1
+  kill_output "$logical"
+  swaybg -o "$output" -i "$file" -m fill &
+  pf="$(pid_file_for "$logical")"; mkdir -p "$(dirname "$pf")"
+  printf '%s\n' "$!" > "$pf"
+  wf="$(wall_file_for "$logical")"; mkdir -p "$(dirname "$wf")"
+  printf '%s\n' "$file" > "$wf"
+  return 0
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: apply_output with selective kill + persistence"
+```
+
+---
+
+## Task 9: wpaper symlink + theme application
+
+`update_wpaper`: symlink `~/.cache/wal/wpaper` → current H image (read from `wall_h`). `apply_theme <theme>`: persist theme, run wal, notify. `finalize <theme>`: wpaper + apply_theme.
+
+**Files:**
+- Modify: `wallp`
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_update_wpaper_symlinks_h() {
+  : > "$HOME/h.png"; mkdir -p "$(dirname "$(wall_file_for H)")"
+  echo "$HOME/h.png" > "$(wall_file_for H)"
+  update_wpaper
+  assert_eq "$HOME/h.png" "$(readlink "$HOME/.cache/wal/wpaper")" "wpaper -> H image"
+}
+test_apply_theme_runs_wal_and_persists() {
+  apply_theme "mytheme"
+  assert_eq "mytheme" "$(cat "$(theme_file)")" "theme persisted"
+  assert_contains "$(cat "$HOME/calls.log")" "wal --backend colorz -nq --theme mytheme -o $HOME/bin/wal.sh" "wal invoked"
+  assert_contains "$(cat "$HOME/calls.log")" "notify-send" "notify sent"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — functions not defined.
+
+- [ ] **Step 3: Implement**
+
+```bash
+update_wpaper() {
+  local wf img link; wf="$(wall_file_for H)"
+  [ -s "$wf" ] || return 0
+  img="$(cat "$wf")"
+  link="$HOME/.cache/wal/wpaper"
+  mkdir -p "$(dirname "$link")"
+  ln -sf "$img" "$link"
+}
+
+apply_theme() {
+  local theme="$1"
+  persist_theme "$theme"
+  wal --backend colorz -nq --theme "$theme" -o "$HOME/bin/wal.sh"
+  command -v notify-send >/dev/null 2>&1 && \
+    notify-send -u normal -t 5000 "color theme update" "setting color theme to: $theme"
+}
+
+finalize() {
+  update_wpaper
+  apply_theme "$1"
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: wpaper symlink + theme application"
+```
+
+---
+
+## Task 10: Restore action
+
+`do_restore <flag_theme>`: for H and V, use persisted `wall_h`/`wall_v` if present else `CONF_DEFAULT_*` (persisting the default); apply_output each; finalize with resolved theme.
+
+**Files:**
+- Modify: `wallp`
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_restore_uses_persisted() {
+  CONF_OUTPUT_H="DP-1" CONF_OUTPUT_V="DP-3" CONF_THEME="conf"
+  CONF_DEFAULT_H="$HOME/dh.png" CONF_DEFAULT_V="$HOME/dv.png"
+  : > "$HOME/saved_h.png"; : > "$HOME/saved_v.png"
+  mkdir -p "$HOME/.config/wallp"
+  echo "$HOME/saved_h.png" > "$(wall_file_for H)"
+  echo "$HOME/saved_v.png" > "$(wall_file_for V)"
+  do_restore ""
+  assert_contains "$(cat "$HOME/calls.log")" "swaybg -o DP-1 -i $HOME/saved_h.png" "H restored from saved"
+  assert_contains "$(cat "$HOME/calls.log")" "swaybg -o DP-3 -i $HOME/saved_v.png" "V restored from saved"
+}
+test_restore_falls_back_to_defaults() {
+  CONF_OUTPUT_H="DP-1" CONF_OUTPUT_V="DP-3" CONF_THEME="conf"
+  : > "$HOME/dh.png"; : > "$HOME/dv.png"
+  CONF_DEFAULT_H="$HOME/dh.png" CONF_DEFAULT_V="$HOME/dv.png"
+  do_restore ""
+  assert_contains "$(cat "$HOME/calls.log")" "swaybg -o DP-1 -i $HOME/dh.png" "H default used"
+  assert_eq "$HOME/dh.png" "$(cat "$(wall_file_for H)")" "default persisted"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `do_restore: command not found`.
+
+- [ ] **Step 3: Implement**
+
+```bash
+# Pick saved path for a logical output, else its conf default.
+restore_path_for() {
+  local logical="$1" wf; wf="$(wall_file_for "$logical")"
+  if [ -s "$wf" ]; then cat "$wf"; return; fi
+  case "$logical" in
+    H) printf '%s\n' "$CONF_DEFAULT_H" ;;
+    V) printf '%s\n' "$CONF_DEFAULT_V" ;;
+  esac
+}
+
+do_restore() {
+  local flag_theme="$1" logical file
+  for logical in H V; do
+    file="$(restore_path_for "$logical")"
+    apply_output "$logical" "$file" || true
+  done
+  finalize "$(resolve_theme "$flag_theme")"
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: restore action (saved -> default fallback)"
+```
+
+---
+
+## Task 11: Set action (CLI args path; qarma path isolated)
+
+`do_set <flag_theme> [H=.. V=..]`: parse args; if neither given and display present → `qarma_select` (separate fn, stubbed in tests); apply each provided; finalize. `qarma_select` populates `SET_H`/`SET_V` via the qarma menu+pickers — isolated so tests drive only the CLI path.
+
+**Files:**
+- Modify: `wallp`
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_set_cli_partial_only_v() {
+  CONF_OUTPUT_H="DP-1" CONF_OUTPUT_V="DP-3" CONF_THEME="conf"
+  : > "$HOME/v.png"
+  do_set "" "V=$HOME/v.png"
+  assert_contains "$(cat "$HOME/calls.log")" "swaybg -o DP-3 -i $HOME/v.png" "V set"
+  case "$(cat "$HOME/calls.log")" in *"swaybg -o DP-1"*) echo "FAIL: H should not be set"; FAIL=$((FAIL+1));; *) PASS=$((PASS+1));; esac
+}
+test_set_cli_theme_flag_persisted() {
+  CONF_OUTPUT_H="DP-1" CONF_OUTPUT_V="DP-3" CONF_THEME="conf"
+  : > "$HOME/h.png"
+  do_set "flagtheme" "H=$HOME/h.png"
+  assert_eq "flagtheme" "$(cat "$(theme_file)")" "flag theme persisted"
+}
+test_set_no_args_no_display_errors() {
+  CONF_OUTPUT_H="DP-1" CONF_OUTPUT_V="DP-3" CONF_THEME="conf"
+  unset WAYLAND_DISPLAY
+  out="$(do_set "" 2>&1)"; rc=$?
+  assert_eq "1" "$rc" "no display no args rc1"
+  assert_contains "$out" "no display" "error mentions display"
+}
+```
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `do_set: command not found`.
+
+- [ ] **Step 3: Implement**
+
+```bash
+# Interactive selection via qarma. Populates SET_H/SET_V. Isolated for testing.
+qarma_select() {
+  local choice file
+  choice="$(qarma --list --title="wallp" --text="Which screen?" \
+    --column="Screen" H V Both 2>/dev/null)" || return 1
+  case "$choice" in
+    H|Both)
+      file="$(qarma --file-selection --preview-images 500 --width 1300 --height 600 \
+        --title='Choose Horizontal Wallpaper')" && SET_H="$file" ;;
+  esac
+  case "$choice" in
+    V|Both)
+      file="$(qarma --file-selection --preview-images 500 --width 1300 --height 600 \
+        --title='Choose Vertical Wallpaper')" && SET_V="$file" ;;
+  esac
+  return 0
+}
+
+do_set() {
+  local flag_theme="$1"; shift
+  SET_H="" SET_V=""
+  if [ "$#" -gt 0 ]; then
+    parse_set_args "$@" || return 1
+  fi
+  if [ -z "$SET_H" ] && [ -z "$SET_V" ]; then
+    if [ -n "${WAYLAND_DISPLAY:-}" ]; then
+      qarma_select || return 1
+    else
+      echo "wallp: no display: pass H=<file> and/or V=<file>" >&2
+      return 1
+    fi
+  fi
+  [ -n "$SET_H" ] && apply_output H "$SET_H" || true
+  [ -n "$SET_V" ] && apply_output V "$SET_V" || true
+  finalize "$(resolve_theme "$flag_theme")"
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: set action (CLI + qarma selection)"
+```
+
+---
+
+## Task 12: Help screen + argument dispatch (`main`)
+
+`show_help` (qarma window if display, else stdout). `main` parses top-level flags `--set --restore --theme <name> --help/-h`, calls `load_conf` (honoring bootstrap rc 10 → exit 0), dispatches.
+
+**Files:**
+- Modify: `wallp` (replace stub `main`, add `show_help`)
+- Test: `tests/run.sh`
+
+- [ ] **Step 1: Write failing tests**
+
+```bash
+test_main_bare_shows_help() {
+  unset WAYLAND_DISPLAY
+  out="$(main 2>&1)"; rc=$?
+  assert_eq "0" "$rc" "help rc0"
+  assert_contains "$out" "Usage" "help text shown"
+}
+test_main_unknown_flag_errors() {
+  out="$(main --bogus 2>&1)"; rc=$?
+  assert_eq "1" "$rc" "unknown flag rc1"
+  assert_contains "$out" "Usage" "help shown on error"
+}
+test_main_bootstrap_exits_zero() {
+  # no conf present -> bootstrap, no wallpaper change
+  out="$(main --restore 2>&1)"; rc=$?
+  assert_eq "0" "$rc" "bootstrap rc0"
+  assert_no_file "$(pid_file_for H)" "no wallpaper set during bootstrap"
+}
+test_main_theme_flag_parsed_with_restore() {
+  mkdir -p "$HOME/.config/wallp"
+  printf '%s\n' 'OUTPUT_H=DP-1' 'OUTPUT_V=DP-3' \
+    'DEFAULT_H=/dh.png' 'DEFAULT_V=/dv.png' > "$HOME/.config/wallp/wallp.conf"
+  : > /dh.png 2>/dev/null || true   # may be unwritable; rely on default-skip
+  main --restore --theme tflag >/dev/null 2>&1
+  assert_eq "tflag" "$(cat "$(theme_file)")" "theme flag honored via main"
+}
+```
+
+Note: `test_main_theme_flag_parsed_with_restore` uses `/dh.png` which likely
+does not exist; `apply_output` will skip (rc1, `|| true`) but `finalize` still
+runs and persists the theme — which is what the assertion checks.
+
+- [ ] **Step 2: Run, verify fail**
+
+Run: `bash tests/run.sh`
+Expected: FAIL — `main` is still the stub returning 0 with no help.
+
+- [ ] **Step 3: Implement** (replace the stub `main`)
+
+```bash
+show_help() {
+  local text="wallp — unified wallpaper manager
+
+Usage:
+  wallp                      Show this help
+  wallp --help | -h          Show this help
+  wallp --set                Interactive (qarma) wallpaper selection
+  wallp --set H=<file>       Set horizontal screen only
+  wallp --set V=<file>       Set vertical screen only
+  wallp --set H=<f> V=<f>    Set both screens
+  wallp --restore            Restore last session (defaults if none)
+  wallp --theme <name>       Override theme (with --set or --restore)
+
+Config: ~/.config/wallp/wallp.conf"
+  if [ -n "${WAYLAND_DISPLAY:-}" ] && command -v qarma >/dev/null 2>&1; then
+    qarma --info --title="wallp help" --text="$text" 2>/dev/null
+  else
+    printf '%s\n' "$text"
+  fi
+}
+
+main() {
+  local action="" flag_theme="" set_args=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --help|-h) show_help; return 0 ;;
+      --set)     action="set" ;;
+      --restore) action="restore" ;;
+      --theme)   shift; flag_theme="${1:-}";
+                 [ -z "$flag_theme" ] && { echo "wallp: --theme needs a name" >&2; return 1; } ;;
+      H=*|V=*)   set_args+=("$1") ;;
+      *)         echo "wallp: unknown argument '$1'" >&2; show_help; return 1 ;;
+    esac
+    shift
+  done
+
+  if [ -z "$action" ]; then show_help; return 0; fi
+
+  load_conf; local rc=$?
+  if [ "$rc" -eq 10 ]; then return 0; fi   # bootstrapped, no change
+  if [ "$rc" -ne 0 ]; then return 1; fi
+
+  case "$action" in
+    set)     do_set "$flag_theme" "${set_args[@]}" ;;
+    restore) do_restore "$flag_theme" ;;
+  esac
+}
+```
+
+- [ ] **Step 4: Run, verify pass**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wallp tests/run.sh
+git commit -m "feat: help screen + main dispatch"
+```
+
+---
+
+## Task 13: Ship example config + make executable
+
+**Files:**
+- Create: `wallp.conf.example`
+- Modify: `wallp` (ensure executable bit)
+
+- [ ] **Step 1: Create `wallp.conf.example`**
+
+```
+# wallp config. Copy to ~/.config/wallp/wallp.conf and edit.
+# THEME is optional (defaults to sexy-splurge).
+THEME=sexy-splurge
+# Physical output names (swaymsg -t get_outputs / wlr-randr)
+OUTPUT_H=DP-1
+OUTPUT_V=DP-3
+# Defaults used by --restore when no saved state exists.
+DEFAULT_H=~/Pictures/wallpapers/SFW/horizontal.png
+DEFAULT_V=~/Pictures/wallpapers/SFW/vertical.png
+```
+
+- [ ] **Step 2: Make wallp executable**
+
+Run: `chmod +x wallp tests/run.sh`
+
+- [ ] **Step 3: Verify full suite green**
+
+Run: `bash tests/run.sh`
+Expected: `FAIL=0`, exit 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add wallp wallp.conf.example tests/run.sh
+git commit -m "chore: ship example config, make wallp executable"
+```
+
+---
+
+## Task 14: Manual smoke test on real two-screen setup
+
+No automated test — real hardware. Document the run; do not commit code unless a bug is found (then add a regression test first).
+
+- [ ] **Step 1: Backup current state**
+
+Run:
+```bash
+cp -a ~/.config/wallp ~/.config/wallp.bak 2>/dev/null || true
+```
+
+- [ ] **Step 2: First run bootstraps conf**
+
+Run: `./wallp --restore`
+Expected: message "generated config at …"; conf file created; **no wallpaper change**. Edit the conf with real output names + default wallpaper paths.
+
+- [ ] **Step 3: Restore with defaults**
+
+Run: `./wallp --restore`
+Expected: both screens show the configured defaults; theme applied; notification appears.
+
+- [ ] **Step 4: Partial CLI set (V only) does not blank H**
+
+Run: `./wallp --set V=/path/to/some/vertical.png`
+Expected: vertical screen changes; **horizontal stays as-is** (not black).
+
+- [ ] **Step 5: qarma flow**
+
+Run: `./wallp --set`
+Expected: qarma menu H/V/Both → file picker(s) → chosen screen(s) update. Cancel skips.
+
+- [ ] **Step 6: Theme persistence across restore**
+
+Run:
+```bash
+./wallp --set H=/some/h.png --theme some-other-theme
+./wallp --restore
+```
+Expected: after restore, `some-other-theme` is reapplied (persisted theme wins), not the conf default.
+
+- [ ] **Step 7: Help**
+
+Run: `./wallp` and `./wallp --help`
+Expected: usage shown (qarma window under wayland, else stdout).
+
+---
+
+## Task 15: Cut over wal.sh and remove old scripts
+
+Only after Task 14 passes. `wal.sh` is outside the repo (`/home/danix/bin/wal.sh`).
+
+- [ ] **Step 1: Trim `wal.sh`**
+
+Edit `/home/danix/bin/wal.sh` — remove the wallpaper-pointer + wpaper logic (old lines 15-27), keeping only dunst + kitty glue. Resulting file:
+
+```sh
+#!/bin/sh
+
+# uncomment for debug
+#set -ex
+
+# Symlink dunst config
+ln -sf ~/.cache/wal/dunstrc ~/.config/dunst/dunstrc
+# Restart dunst with the new color scheme
+pkill dunst
+dunst &
+
+# symlink kitty colors
+ln -sf ~/.cache/wal/colors-kitty.conf ~/.config/kitty/current-theme.conf
+```
+
+- [ ] **Step 2: Verify wpaper still maintained**
+
+Run: `./wallp --restore && readlink ~/.cache/wal/wpaper`
+Expected: symlink points at current H image (wallp now owns it). Confirm rofi menus still themed.
+
+- [ ] **Step 3: Remove superseded scripts**
+
+Run:
+```bash
+git rm multiwal.sh qar-lastwall.sh
+```
+
+- [ ] **Step 4: Update any autostart references**
+
+Manually check the wayland/hyprland autostart (e.g. hyprland config `exec-once`) that called `qar-lastwall.sh` — repoint to `wallp --restore`. Document the file edited in the commit body.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "chore: cut over to wallp, remove multiwal.sh + qar-lastwall.sh"
+```
+
+---
+
+## Self-Review Notes
+
+- Spec coverage: CLI forms (T7,T11,T12), conf bootstrap + hard-error (T4), logical H/V mapping (T6), theme persistence + precedence (T5, asserted via T11/T12), selective per-output kill / no-blank partial (T8, asserted T11), wpaper kept for rofi (T9,T15), drop wal/wal2 (no writes anywhere in plan — verified), restore saved→default (T10), help (T12), error handling (T4,T7,T8,T11,T12). All covered.
+- Naming consistency: `apply_output`, `output_for`, `wall_file_for`, `pid_file_for`, `resolve_theme`, `persist_theme`, `do_set`, `do_restore`, `finalize`, `update_wpaper`, `apply_theme`, `parse_conf`, `load_conf`, `parse_set_args` — used consistently across tasks.
+- No placeholders: all steps carry real code/commands/expected output.