From c97dd018b6baa881c16b4c7c4d94554ce58a2b3c Mon Sep 17 00:00:00 2001
From: elwrcl <elwerici@proton.me>
Date: Sat, 3 Oct 2026 03:38:57 +0300
Subject: [PATCH] docs: README and home-manager checklist

---
 README.md              | 102 +++++++++++++++++++++++++++++++++++++++++
 docs/test-checklist.md |   7 +++
 2 files changed, 109 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c4c6b0b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,102 @@
+# valw
+
+macOS-style screenshots for [niri](https://github.com/YaLTeR/niri) on
+Wayland: the whole screen, a region, a window, a zoomable freeze-frame, a
+Cmd+Shift+5-style toolbar, a floating preview you can drag into other apps,
+and a built-in markup editor. Written in Rust, packaged with Nix.
+
+## Install
+
+Run it once:
+
+```sh
+nix run git+https://git.userevolt.app/elars/valw -- doctor
+```
+
+As a package from the flake (`packages.<system>.default`), or with the
+home-manager module:
+
+```nix
+# flake.nix
+inputs.valw.url = "git+https://git.userevolt.app/elars/valw";
+
+# a home-manager module
+{ inputs, ... }:
+{
+  imports = [ inputs.valw.homeModules.default ];
+
+  programs.valw = {
+    enable = true;
+    settings = {
+      preview.timeout_secs = 3;
+      sound.volume = 0.4;
+      capture.window_shadow = true;
+    };
+  };
+}
+```
+
+`settings` becomes `~/.config/valw/config.toml`. valw checks it while the
+configuration is built, so a typo or a bad value fails the rebuild instead
+of surprising you later. The toolbar's remembered choices live in
+`~/.local/state/valw/toolbar.toml` and stay writable.
+
+## Bind it in niri
+
+```kdl
+binds {
+    Print           { spawn "valw" "screen"; }
+    Mod+Shift+S     { spawn "valw" "region"; }
+    Mod+Shift+W     { spawn "valw" "window"; }
+    Mod+Shift+Z     { spawn "valw" "zoom"; }
+    Mod+Shift+T     { spawn "valw" "toolbar"; }
+}
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `valw screen [--all]` | The focused output (or every output) |
+| `valw region` | Drag a region; Shift locks an axis, Alt grows from the centre, Space moves it; Space before dragging switches to window mode |
+| `valw window` | Click a window |
+| `valw zoom` | Freeze the screen and zoom: wheel, drag, `f` flashlight, `c` capture the view, `0` reset, Esc |
+| `valw toolbar` | Pick a mode from a floating bar, with a timer and options |
+| `valw edit FILE` | The markup editor (clicking a preview opens it) |
+| `valw doctor` | What the compositor and system support |
+
+Capture commands take `--clipboard-only`, `-o PATH` (`-` for stdout),
+`--delay SECS`, `--cursor` and `--no-preview`.
+
+## Configuration
+
+Every key is optional; these are the defaults.
+
+```toml
+[save]
+directory = "~/Pictures/Screenshots"
+filename = "Screenshot %Y-%m-%d at %H.%M.%S.png"
+copy_to_clipboard = true
+
+[capture]
+show_cursor = false
+window_shadow = false
+
+[preview]
+enabled = true
+timeout_secs = 5
+
+[zoom]
+scroll_step = 1.15
+flashlight_radius = 180
+
+[editor]
+backend = "builtin"   # or "satty"
+
+[sound]
+enabled = true
+volume = 0.6
+combo_reset_secs = 5
+```
+
+Logs are in `~/.local/state/valw/logs/`.
diff --git a/docs/test-checklist.md b/docs/test-checklist.md
index 40e0fcd..e055a39 100644
--- a/docs/test-checklist.md
+++ b/docs/test-checklist.md
@@ -153,3 +153,10 @@ image, a cancel brought the thumbnail back, and a swipe still dismissed it.
 - Without `XDG_RUNTIME_DIR` the sound cache and combo state in `/tmp` are shared between users.
 - `pipewire` on the wrapper's PATH adds its whole closure to the package.
 - Tuning by ear: shots 6–7 are about 9–10 dB louder than 1–5; adjust with `__combo-demo`.
+
+## home-manager module
+
+- [ ] copland: `home-valw.ulu.nix` uses `inputs.valw.homeModules.default` with `programs.valw.enable = true` and a few `settings`; rebuild; `~/.config/valw/config.toml` is the store file with those settings.
+- [ ] A typo in `settings` (e.g. `preview.timout_secs`) fails the rebuild naming the key.
+- [ ] The toolbar still remembers its options (state file stays writable).
+- [ ] New binds for `valw window`, `valw zoom`, `valw toolbar` in copland's niri keybinds.