docs: add CLAUDE.md and README.md

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

1 files changed, 82 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2aa4393
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+Guidance for AI agents working in this repo.
+
+## What this is
+
+`wallp` — a single bash script that sets and restores wallpapers on a fixed
+two-screen wayland (sway/hyprland) setup. It merges two older scripts
+(`multiwal.sh` interactive setter, `qar-lastwall.sh` restorer). Uses `swaybg` to
+paint wallpapers, `qarma` for GUI selection, `wal` (pywal) for the color theme.
+
+Logical screens are `H` (horizontal) and `V` (vertical), mapped to physical
+outputs via config (`OUTPUT_H`/`OUTPUT_V`).
+
+## Layout
+
+- `wallp` — the whole program (one bash file, ~320 lines).
+- `tests/wallp.bats` — bats test suite (the only tests).
+- `wallp.conf.example` — sample config.
+- `docs/superpowers/specs/` — design spec.
+- `docs/superpowers/plans/` — implementation plan.
+
+## Build / test
+
+No build step. Run the suite:
+
+```bash
+bats tests/wallp.bats
+```
+
+Requires `bats` (1.5.0 known good). Tests run hermetically: `setup()` creates a
+temp `$HOME`, stubs `swaybg`/`wal`/`qarma`/`notify-send`/`pkill`/`kill` on `PATH`
+(each logs its call to `$HOME/calls.log` and exits 0), then `source`s `wallp`.
+The sourcing guard at EOF (`[ "${BASH_SOURCE[0]}" = "$0" ]`) keeps `main` from
+running on source — **do not remove it.**
+
+Syntax check: `bash -n wallp`.
+
+## Development rules
+
+- **TDD.** Every change: write the failing bats test first, confirm it fails,
+  implement, confirm green, commit. Functions go ABOVE `main()`.
+- **Test conventions:** use `run fn` when asserting on `$status`/`$output`; call
+  the function directly when asserting on globals (`CONF_*`, `SET_*`) or
+  filesystem side effects, since `run` executes in a subshell.
+- **Pure logic is unit-testable** (conf parse, arg parse, tilde expansion, output
+  mapping, theme resolution). Side-effecting bits (`swaybg`, `wal`, `qarma`) are
+  isolated in thin functions and exercised via the PATH stubs.
+- `set -u` is on. Empty-array expansion `"${set_args[@]}"` is safe on bash ≥ 4.4
+  (this host is fine). Guard env vars with `${VAR:-}`.
+- Quote all paths (wallpaper filenames may contain spaces).
+
+## Critical gotchas
+
+- **Install is a COPY, not a symlink.** The live binary is `~/bin/wallp`, copied
+  from this repo. After editing repo `wallp`, re-copy:
+  `cp /home/danix/Programming/GIT/wallp/wallp ~/bin/wallp`
+  Otherwise hypr autostart/keybind run the stale version.
+- **qarma `--list` needs `--radiolist --print-column=2`.** A plain `--list`
+  prints nothing on selection (bug that shipped once). `qarma_select` depends on
+  these flags; a regression test guards it.
+- **Selective kill.** `apply_output` kills only the changed output's swaybg PID
+  (tracked in `~/.cache/wallp/{H,V}.pid`). Updating one screen must never blank
+  the other — there's a test for this; keep it green.
+- **`load_conf` return codes:** 0 ok, 1 invalid (missing required key), 10
+  bootstrapped (template just written → caller exits 0, no wallpaper change).
+- **Persistence is wallp-owned**, under `~/.config/wallp/` (`wall_h`, `wall_v`,
+  `theme`). `~/.cache/wal/wpaper` symlink is still maintained (rofi reads it).
+  `~/bin/wal.sh` was trimmed to dunst+kitty glue only; it no longer touches
+  wallpaper pointers.
+
+## External integration (outside this repo)
+
+- `~/bin/wal.sh` — wal's `-o` hook; dunst + kitty theming only now.
+- `~/.config/hypr/sections/autostart.lua` → `wallp --restore`.
+- `~/.config/hypr/sections/keybindings.lua` → `wallp --set` (mainMod+Return).
+- Old `~/bin/multiwal.sh` + `qar-lastwall.sh` kept as fallback, unreferenced.
+
+## Commits
+
+Pre-commit gitleaks hook prints ASCII art — normal; the commit succeeds when it
+reports "no leaks found".