🚀 CD: 😡

.gitea/workflows/release.yml

@@ -0,0 +1,145 @@
+name: CI/CD
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    name: Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Extract Version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
+
+      - name: Generate PKGBUILD
+        run: |
+          TAR_URL="https://git.uyani.de/Uyanide/WallReel/archive/v${{ env.VERSION }}.tar.gz"
+
+          wget -qO source.tar.gz "$TAR_URL"
+          SHA256=$(sha256sum source.tar.gz | awk '{print $1}')
+
+          cat << 'EOF' > PKGBUILD
+          # Maintainer: Uyanide <me@uyani.de>
+          pkgname=wallreel
+          pkgver=${{ env.VERSION }}
+          pkgrel=1
+          pkgdesc="Choose and set desktop wallpapers with customizable themes and actions"
+          arch=('x86_64')
+          url="https://git.uyani.de/Uyanide/WallReel"
+          license=('MIT')
+          depends=('qt6-base' 'qt6-declarative' 'gcc-libs' 'glibc')
+          makedepends=('cmake')
+          source=("${pkgname}-${pkgver}.tar.gz::https://git.uyani.de/Uyanide/WallReel/archive/v${pkgver}.tar.gz")
+          sha256sums=('INSERT_SHA256_HERE')
+
+          build() {
+              cd "wallreel"
+              cmake -B build -S . \
+                  -DCMAKE_BUILD_TYPE='Release' \
+                  -DCMAKE_INSTALL_PREFIX='/usr' \
+                  -Wno-dev
+              cmake --build build
+          }
+
+          package() {
+              cd "wallreel"
+              DESTDIR="$pkgdir" cmake --install build
+              install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
+          }
+          EOF
+
+          sed -i "s/INSERT_SHA256_HERE/$SHA256/" PKGBUILD
+
+      - name: Build and Generate AUR Meta
+        run: |
+          tar -cf - . | docker run --rm -i archlinux:latest /bin/bash -e -c "
+            mkdir -p /workspace && cd /workspace
+            tar -xf -
+            exec 3>&1 1>&2
+
+            pacman-key --init && pacman-key --populate
+            pacman -Sy --noconfirm archlinux-keyring
+            pacman -Su --noconfirm base-devel cmake qt6-base qt6-declarative sudo
+
+            useradd -m builduser
+            chown -R builduser:builduser /workspace
+            echo 'builduser ALL=(ALL) NOPASSWD: ALL' >> /etc/sudoers
+
+            su - builduser -c 'cd /workspace && makepkg -sf --noconfirm'
+            su - builduser -c 'cd /workspace && makepkg --printsrcinfo' > SRCINFO.txt
+
+            tar -cf - *.pkg.tar.zst PKGBUILD SRCINFO.txt >&3
+          " | tar -xf -
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: release-artifacts
+          path: |
+            *.pkg.tar.zst
+            PKGBUILD
+            SRCINFO.txt
+
+  release:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Extract Version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: release-artifacts
+          path: .
+
+      - name: Publish to Gitea Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: WallReel ${{ env.VERSION }}
+          draft: false
+          prerelease: false
+          files: "*.pkg.tar.zst"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to AUR
+        env:
+          AUR_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "$AUR_KEY" > ~/.ssh/aur
+          chmod 600 ~/.ssh/aur
+          ssh-keyscan aur.archlinux.org >> ~/.ssh/known_hosts
+
+          cat <<EOF > ~/.ssh/config
+          Host aur.archlinux.org
+            IdentityFile ~/.ssh/aur
+            User aur
+          EOF
+
+          git config --global user.name "Uyanide"
+          git config --global user.email "me@uyani.de"
+
+          git clone ssh://aur@aur.archlinux.org/wallreel.git aur-repo
+          cp PKGBUILD aur-repo/
+          cp SRCINFO.txt aur-repo/.SRCINFO
+          cd aur-repo
+
+          cat << 'EOF' > LICENSE
+          Copyright (C) 2026 by Uyanide me@uyani.de
+
+          Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+          THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+          EOF
+
+          git add PKGBUILD LICENSE .SRCINFO
+          git commit -m "Release v${{ env.VERSION }}"
+          git push origin master

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.16)
 
-project(WallReel VERSION 2.0.0 LANGUAGES CXX)
+project(WallReel VERSION 2.0.1 LANGUAGES CXX)
 
 set(EXECUTABLE_NAME "wallreel")
 set(CORELIB_NAME "wallreel-core")

README.md

@@ -1,20 +1,20 @@
 ## What this is
 
-It might not be that worthy to build a Qt application from ground for such a small feature, but I kind of enjoy the pain... So here it is.
+It might be a bit overkill to build a Qt application from ground for such a small feature, but I kind of enjoy the pain... So here it is.
 
-<img src="https://raw.githubusercontent.com/Uyanide/WallReel/refs/heads/master/misc/screenshot.webp"/>
+![WallReel screenshot](misc/screenshot.webp)
 
 ## How to build
 
-1. Make sure you have Qt6 libraries, CMake and a C++ compiler installed.
+1. Make sure Qt6 libraries, CMake, and a C++ compiler are installed.
 
-   e.g. On Arch-based systems:
+   On Arch-based systems:
 
    ```bash
    sudo pacman -S --needed qt6-base qt6-declarative cmake gcc
    ```
 
-   on Debian-based systems:
+   On Debian-based systems:
 
    ```bash
    sudo apt install --no-install-recommends qt6-base-dev qt6-declarative-dev qml6-module-qtquick qml6-module-qtquick-controls2 qml6-module-qtquick-layouts qml6-module-qtquick-templates qml6-qtqml-workerscript cmake g++
@@ -29,31 +29,57 @@ It might not be that worthy to build a Qt application from ground for such a sma
 
 3. Build and install:
 
-   This is a standard CMake managed project, so the build process is pretty normal and straightforward. First, configure the project:
+   This is a standard CMake project. First, configure it. Adjust the install prefix as needed.
 
    ```bash
    cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr/local
    ```
 
-   Adjust install prefix to your needs. Start building:
+   Then build.
 
    ```bash
    cmake --build build -- -j$(nproc)
    ```
 
-   The binary will be located at `build/wallreel` and can be run directly for testing:
+   The binary will be located at `build/wallreel` and can be run directly for testing.
 
    ```bash
    build/wallreel
    ```
 
-   Install it to the previously specified prefix. This step may require root permissions if the install prefix is set to a system directory like `/usr/local`.
+   Install to the configured prefix. This step may require root permissions if the prefix is set to a system path such as `/usr/local`.
 
    ```bash
    cmake --install build --strip
    ```
 
-   `--strip` option is used to reduce the binary size by removing symbol information, which is generally not needed for normal usage.
+   `--strip` reduces binary size by removing symbol information that is usually unnecessary for normal usage.
+
+## Man Pages
+
+This project ships man pages and installs them through `cmake --install`.
+
+- `wallreel(1)` for CLI usage
+- `wallreel(5)` for configuration
+
+The source files are maintained in Markdown for easier editing:
+
+- `docs/man/man.1.md`
+- `docs/man/man.5.md`
+
+Generated man files are committed for packaging and normal installation without extra tool dependencies:
+
+- `WallReel/Assets/man/man.1`
+- `WallReel/Assets/man/man.5`
+
+To regenerate them, run:
+
+```bash
+for src in docs/man/man.*.md; do
+    dst="WallReel/Assets/man/$(basename "${src%.md}")"
+    pandoc --from gfm --to man --standalone -o "$dst" "$src"
+done
+```
 
 ## Configuration Reference
 
@@ -75,9 +101,9 @@ Defines where WallReel looks for images and what to exclude. If none of the `pat
 
 Configures the color palettes.
 
-By default, a **dominant color** will be extracted from each wallpaper. If a palette is **selected**, the color that matches the dominant color the best will be selected as the **primary color**. This might be convinient if you prefer to set your desktop theme to match the wallpaper using a predefined palette (e.g. Catppuccin, Tokyo Night) instead of generating a custom one (e.g. using matugen).
+By default, a **dominant color** is extracted from each wallpaper. If a palette is **selected**, the closest palette color is used as the **primary color**. This is useful when you want your desktop theme to follow a predefined palette (for example Catppuccin or Tokyo Night) instead of generating a custom one (for example with matugen).
 
-There are a few embeded palettes available in the application, including "Catppuccin Frappe", "Catppuccin Latte", "Catppuccin Macchiato", and "Catppuccin Mocha". You can also define your own palettes or override the embeded ones by providing a custom configuration.
+Several embedded palettes are available, including "Catppuccin Frappe", "Catppuccin Latte", "Catppuccin Macchiato", and "Catppuccin Mocha". You can also define custom palettes or override embedded ones via configuration.
 
 | Property   | Type             | Default | Description                                                                                                                                 |
 | :--------- | :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -194,26 +220,27 @@ Controls what UI state is persisted between sessions.
 
 ## CLI
 
-```
+```text
 Usage: wallreel [options]
 
 Options:
   -h, --help                 Displays help on commandline options.
   -v, --version              Displays version information.
   -V, --verbose              Set log level to DEBUG (default is INFO)
-  -C, --clear-cache         Clear the cache and exit
+  -C, --clear-cache          Clear the image cache and exit
   -q, --quiet                Suppress all log output
   -d, --append-dir <dir>     Append an additional wallpaper search directory
   -c, --config-file <file>   Specify a custom configuration file
+  -D, --disable-actions      Disable actions set in configuration file
   -a, --apply <file>         Apply the specified image as wallpaper and exit
 ```
 
 A few things to notice:
 
-- It's generally not necessary to provide any CLI arguments, I would recommend using the config file to customize the behavior instead. However, it is still possible to control some essential options via CLI.
+- In most cases you do not need CLI arguments; configuration is usually the better place to customize behavior. CLI flags are still useful for quick overrides and one-shot runs though.
 
 - The `--append-dir` option can be used multiple times to add multiple directories.
 
 - It is quite obvious that some options conflicts with each other (e.g. `--verbose` and `--quiet`). Case mutually exclusive options are provided together, the behavior is un.. just please, don't do that.
 
-- Given `--apply`, the config file (default or specified with `--config-file`) will be parsed, and the `onSelected` action will be executed with the properties of the specified image available for placeholders. If `savePalette` is enabled and a palette is selected in the last session, `palette`, `colorName` and `colorHex` placeholders will also be available. `saveState` commands will also be executed to fetch states for placeholders. After the action is executed, the application will exit immediately without showing the UI. This allows you to use WallReel as a command-line wallpaper setter that also supports palette-based theming and state management.
+- With `--apply`, WallReel still parses the configuration (default path or `--config-file`) and executes `onSelected` with placeholders resolved from the specified image. If `savePalette` is enabled and a palette was selected in the last session, `palette`, `colorName`, and `colorHex` placeholders are also available. `saveState` commands are executed as well. The application exits immediately after executing the action, without opening the UI. This mode allows WallReel to be used as a command-line wallpaper setter with palette-aware theming and state placeholders.

WallReel/Assets/CMakeLists.txt

@@ -17,3 +17,13 @@ install(FILES ${CMAKE_CURRENT_LIST_DIR}/icon.svg
     DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/scalable/apps
     RENAME ${EXECUTABLE_NAME}.svg
 )
+
+install(FILES ${CMAKE_CURRENT_LIST_DIR}/man/man.1
+    DESTINATION ${CMAKE_INSTALL_MANDIR}/man1
+    RENAME ${EXECUTABLE_NAME}.1
+)
+
+install(FILES ${CMAKE_CURRENT_LIST_DIR}/man/man.5
+    DESTINATION ${CMAKE_INSTALL_MANDIR}/man5
+    RENAME ${EXECUTABLE_NAME}.5
+)

WallReel/Assets/app.desktop

@@ -3,10 +3,10 @@ Version=1.0
 Type=Application
 Name=WallReel
 Icon=wallreel
-GenericName=Animated wallpaper selector
+GenericName=Wallpaper Selector
 TryExec=wallreel
 Exec=wallreel
-Comment=A small wallpaper utility made with Qt
+Comment=Choose and set desktop wallpapers with customizable themes and actions
 Terminal=false
 Categories=Application;Utility;DesktopSettings;
 StartupNotify=true

WallReel/Assets/apply.desktop

@@ -4,10 +4,10 @@ Type=Application
 Name=Apply with WallReel
 Icon=wallreel
 NoDisplay=true
-GenericName=Animated wallpaper selector
+GenericName=Wallpaper Selector
 TryExec=wallreel
 Exec=wallreel -a %f
-Comment=A small wallpaper utility made with Qt
+Comment=Choose and set desktop wallpapers with customizable themes and actions
 Terminal=false
 Categories=Application;Utility;DesktopSettings;
 StartupNotify=true

WallReel/Assets/man/man.1

@@ -0,0 +1,89 @@
+.\" Automatically generated by Pandoc 3.5
+.\"
+.TH "WALLREEL" "1" "2026\-03\-24" "WallReel 2.0.1" "User Commands"
+.SH NAME
+wallreel \- Choose and set desktop wallpapers with customizable themes
+and actions
+.SH SYNOPSIS
+\f[B]wallreel\f[R] [\f[I]options\f[R]]
+.SH DESCRIPTION
+\f[B]wallreel\f[R] is a Qt6 application for browsing wallpaper images,
+previewing candidates, and applying a selected image.
+.PP
+Configuration is loaded from a JSON file.
+CLI options are available for logging, one\-shot operations, and runtime
+overrides.
+.SH OPTIONS
+\f[B]\-h, \-\-help\f[R] : Display help for command\-line options.
+.PP
+\f[B]\-v, \-\-version\f[R] : Display version information.
+.PP
+\f[B]\-V, \-\-verbose\f[R] : Set log level to DEBUG (default is INFO).
+.PP
+\f[B]\-C, \-\-clear\-cache\f[R] : Clear image cache and exit.
+.PP
+\f[B]\-q, \-\-quiet\f[R] : Suppress log output.
+.PP
+\f[B]\-d, \-\-append\-dir\f[R] \f[I]dir\f[R] : Append an additional
+wallpaper search directory.
+.PP
+This option can be provided multiple times.
+.PP
+\f[B]\-c, \-\-config\-file\f[R] \f[I]file\f[R] : Use a custom
+configuration file.
+.PP
+\f[B]\-D, \-\-disable\-actions\f[R] : Disable actions defined in the
+configuration file.
+.PP
+\f[B]\-a, \-\-apply\f[R] \f[I]file\f[R] : Apply the specified image as
+wallpaper and exit.
+.PP
+In this mode, the configuration is still parsed.
+Action placeholders are resolved from the selected image and any
+captured state values.
+.SH BEHAVIOR NOTES
+.IP \[bu] 2
+CLI options are generally optional; configuration is the preferred
+customization path.
+.IP \[bu] 2
+Some options are mutually exclusive (for example \f[CR]\-\-verbose\f[R]
+and \f[CR]\-\-quiet\f[R]).
+.IP \[bu] 2
+With \f[CR]\-\-apply\f[R], WallReel executes configured selection
+actions without opening the UI.
+.SH FILES
+\f[CR]\[ti]/.config/wallreel/config.json\f[R] : Default configuration
+file location.
+.PP
+\f[CR]\[ti]/.cache/wallreel/\f[R] : Runtime cache location.
+.SH EXAMPLES
+Run with default configuration:
+.IP
+.EX
+wallreel
+.EE
+.PP
+Use a custom configuration file:
+.IP
+.EX
+wallreel \-\-config\-file \[ti]/.config/wallreel/config.json
+.EE
+.PP
+Append additional search directories:
+.IP
+.EX
+wallreel \-\-append\-dir \[ti]/Pictures/Wallpapers \-\-append\-dir \[ti]/Art
+.EE
+.PP
+Apply a wallpaper and exit:
+.IP
+.EX
+wallreel \-\-apply \[ti]/Pictures/wallpaper.jpg
+.EE
+.SH EXIT STATUS
+Returns \f[CR]0\f[R] on success.
+Returns a non\-zero value on failure.
+.SH SEE ALSO
+\f[B]wallreel\f[R](5)
+.SH AUTHOR
+Uyanide <github.com/Uyanide>

WallReel/Assets/man/man.5

@@ -0,0 +1,219 @@
+.\" Automatically generated by Pandoc 3.5
+.\"
+.TH "WALLREEL" "5" "2026\-03\-24" "WallReel 2.0.1" "File Formats Manual"
+.SH NAME
+wallreel\-config \- configuration format for wallreel
+.SH SYNOPSIS
+\f[CR]\[ti]/.config/wallreel/config.json\f[R]
+.SH DESCRIPTION
+WallReel reads configuration from a JSON document.
+The root object is divided into five sections:
+.IP \[bu] 2
+\f[CR]wallpaper\f[R]
+.IP \[bu] 2
+\f[CR]theme\f[R]
+.IP \[bu] 2
+\f[CR]action\f[R]
+.IP \[bu] 2
+\f[CR]style\f[R]
+.IP \[bu] 2
+\f[CR]cache\f[R]
+.PP
+For complete machine\-readable validation details, refer to
+\f[CR]config.schema.json\f[R].
+.SH WALLPAPER SECTION
+Defines where WallReel looks for images and what to exclude.
+.PP
+If both \f[CR]paths\f[R] and \f[CR]dirs\f[R] are empty or omitted,
+WallReel defaults to recursively scanning the user\[aq]s Pictures
+directory and treating all supported image files as wallpaper
+candidates.
+.PP
+\f[CR]paths\f[R] (array of string, default: \f[CR][]\f[R]) : Exact paths
+to specific image files.
+.PP
+\f[CR]dirs\f[R] (array of object, default: \f[CR][]\f[R]) : Directories
+to scan for images.
+.PP
+Each item has:
+.IP \[bu] 2
+\f[CR]path\f[R] (string)
+.IP \[bu] 2
+\f[CR]recursive\f[R] (boolean)
+.PP
+\f[CR]excludes\f[R] (array of string, default: \f[CR][]\f[R]) : Exclude
+patterns as regular expressions.
+.SH THEME SECTION
+Configures color palettes.
+.PP
+A dominant color is extracted from each wallpaper.
+If a palette is selected, WallReel picks the closest palette color as
+the primary color.
+.PP
+\f[CR]palettes\f[R] (array of object, default: \f[CR][]\f[R]) : Custom
+palette definitions.
+.PP
+Each palette has:
+.IP \[bu] 2
+\f[CR]name\f[R] (string)
+.IP \[bu] 2
+\f[CR]colors\f[R] (array)
+.PP
+Each color item has:
+.IP \[bu] 2
+\f[CR]name\f[R] (string)
+.IP \[bu] 2
+\f[CR]value\f[R] (hex string, for example \f[CR]\[dq]#89b4fa\[dq]\f[R])
+.SH ACTION SECTION
+Configures commands executed for preview, selection, and restore
+behavior.
+.PP
+\f[CR]previewDebounceTime\f[R] (integer, default: \f[CR]300\f[R]) :
+Debounce interval in milliseconds for preview actions.
+.PP
+\f[CR]printSelected\f[R] (boolean, default: \f[CR]true\f[R]) : Print
+selected wallpaper path to stdout on confirmation.
+.PP
+\f[CR]printPreview\f[R] (boolean, default: \f[CR]false\f[R]) : Print
+previewed wallpaper path to stdout on preview.
+.PP
+\f[CR]onSelected\f[R] (string, default: \f[CR]\[dq]\[dq]\f[R]) : Command
+executed when a wallpaper is confirmed.
+.PP
+\f[CR]onPreview\f[R] (string, default: \f[CR]\[dq]\[dq]\f[R]) : Command
+executed when a wallpaper is previewed.
+.PP
+\f[CR]saveState\f[R] (array of object, default: \f[CR][]\f[R]) :
+Commands for capturing system values before changing wallpaper.
+.PP
+Each item has:
+.IP \[bu] 2
+\f[CR]key\f[R] (placeholder key)
+.IP \[bu] 2
+\f[CR]fallback\f[R] (default value)
+.IP \[bu] 2
+\f[CR]command\f[R] (stdout\-mapped command)
+.IP \[bu] 2
+\f[CR]timeout\f[R] (milliseconds)
+.PP
+\f[CR]onRestore\f[R] (string, default: \f[CR]\[dq]\[dq]\f[R]) : Command
+executed on restore.
+Saved state keys are usable as placeholders.
+.PP
+\f[CR]quitOnSelected\f[R] (boolean, default: \f[CR]false\f[R]) : Exit
+application immediately after confirming a selection.
+.PP
+\f[CR]restoreOnClose\f[R] (boolean, default: \f[CR]true\f[R]) : Run
+\f[CR]onRestore\f[R] when application closes without a final selection.
+.SS ACTION PLACEHOLDERS
+The following placeholders are available in \f[CR]onSelected\f[R],
+\f[CR]onPreview\f[R], and \f[CR]onRestore\f[R] (where applicable):
+.PP
+\f[CR]{{ path }}\f[R] : Full path of selected or previewed wallpaper.
+.PP
+\f[CR]{{ name }}\f[R] : File name of selected or previewed wallpaper.
+.PP
+\f[CR]{{ size }}\f[R] : Size in bytes of selected or previewed
+wallpaper.
+.PP
+\f[CR]{{ palette }}\f[R] : Selected palette name
+(\f[CR]\[dq]null\[dq]\f[R] if none).
+.PP
+\f[CR]{{ colorName }}\f[R] : Chosen primary color name
+(\f[CR]\[dq]null\[dq]\f[R] if none).
+.PP
+\f[CR]{{ colorHex }}\f[R] : Chosen primary color hex
+(\f[CR]\[dq]null\[dq]\f[R] if none).
+.PP
+\f[CR]{{ domColorHex }}\f[R] : Dominant color hex extracted from the
+wallpaper.
+.PP
+\f[CR]{{ <key> }}\f[R] : Value of a saved state item with matching key.
+.SH STYLE SECTION
+Controls window layout and thumbnail dimensions.
+.PP
+\f[CR]image_width\f[R] (integer, default: \f[CR]320\f[R]) : Width of
+each thumbnail.
+.PP
+\f[CR]image_height\f[R] (integer, default: \f[CR]180\f[R]) : Height of
+each thumbnail.
+.PP
+\f[CR]image_focus_scale\f[R] (number, default: \f[CR]1.5\f[R]) : Focus
+scale multiplier for highlighted thumbnail.
+.PP
+\f[CR]window_width\f[R] (integer, default: \f[CR]750\f[R]) : Initial
+window width.
+.PP
+\f[CR]window_height\f[R] (integer, default: \f[CR]500\f[R]) : Initial
+window height.
+.SH CACHE SECTION
+Controls persisted UI state.
+.PP
+\f[CR]saveSortMethod\f[R] (boolean, default: \f[CR]true\f[R]) : Persist
+sort method and direction.
+.PP
+\f[CR]savePalette\f[R] (boolean, default: \f[CR]true\f[R]) : Persist
+selected palette.
+.PP
+\f[CR]maxImageEntries\f[R] (integer, default: \f[CR]1000\f[R]) : Maximum
+number of image cache entries.
+Older entries are evicted.
+.SH EXAMPLE
+.IP
+.EX
+{
+  \[dq]$schema\[dq]: \[dq]https://raw.githubusercontent.com/Uyanide/WallReel/refs/heads/master/config.schema.json\[dq],
+  \[dq]wallpaper\[dq]: {
+    \[dq]paths\[dq]: [\[dq]/home/user/Pictures/favorite.jpg\[dq]],
+    \[dq]dirs\[dq]: [
+      {
+        \[dq]path\[dq]: \[dq]/home/user/Pictures/Wallpapers\[dq],
+        \[dq]recursive\[dq]: \f[B]true\f[R]
+      }
+    ],
+    \[dq]excludes\[dq]: [\[dq]\[rs]\[rs].gif$\[dq]]
+  },
+  \[dq]theme\[dq]: {
+    \[dq]palettes\[dq]: [
+      {
+        \[dq]name\[dq]: \[dq]Dark\[dq],
+        \[dq]colors\[dq]: [
+          { \[dq]name\[dq]: \[dq]blue\[dq], \[dq]value\[dq]: \[dq]#89b4fa\[dq] },
+          { \[dq]name\[dq]: \[dq]red\[dq], \[dq]value\[dq]: \[dq]#f38ba8\[dq] }
+        ]
+      }
+    ]
+  },
+  \[dq]action\[dq]: {
+    \[dq]previewDebounceTime\[dq]: 500,
+    \[dq]quitOnSelected\[dq]: \f[B]true\f[R],
+    \[dq]onPreview\[dq]: \[dq]swww img {{ path }}\[dq],
+    \[dq]onSelected\[dq]: \[dq]cp {{ path }} \[ti]/.config/wallpaper/current/ && swww img {{ path }}\[dq],
+    \[dq]saveState\[dq]: [
+      {
+        \[dq]key\[dq]: \[dq]current_wp\[dq],
+        \[dq]fallback\[dq]: \[dq]/home/user/Pictures/default.jpg\[dq],
+        \[dq]command\[dq]: \[dq]find \[ti]/.config/wallpaper/current \-type f | head \-n 1\[dq],
+        \[dq]timeout\[dq]: 1000
+      }
+    ],
+    \[dq]onRestore\[dq]: \[dq]swww img {{ current_wp }}\[dq]
+  },
+  \[dq]style\[dq]: {
+    \[dq]image_width\[dq]: 640,
+    \[dq]image_height\[dq]: 400,
+    \[dq]image_focus_scale\[dq]: 1.2,
+    \[dq]window_width\[dq]: 1280,
+    \[dq]window_height\[dq]: 720
+  },
+  \[dq]cache\[dq]: {
+    \[dq]saveSortMethod\[dq]: \f[B]true\f[R],
+    \[dq]savePalette\[dq]: \f[B]true\f[R],
+    \[dq]maxImageEntries\[dq]: 300
+  }
+}
+.EE
+.SH SEE ALSO
+\f[B]wallreel\f[R](1)
+.SH AUTHOR
+Uyanide <github.com/Uyanide>

docs/man/man.1.md

@@ -0,0 +1,109 @@
+---
+title: WALLREEL
+section: 1
+header: User Commands
+footer: WallReel 2.0.1
+date: 2026-03-24
+---
+
+# NAME
+
+wallreel - Choose and set desktop wallpapers with customizable themes and actions
+
+# SYNOPSIS
+
+**wallreel** [*options*]
+
+# DESCRIPTION
+
+**wallreel** is a Qt6 application for browsing wallpaper images, previewing candidates,
+and applying a selected image.
+
+Configuration is loaded from a JSON file. CLI options are available for logging,
+one-shot operations, and runtime overrides.
+
+# OPTIONS
+
+**-h, --help**
+: Display help for command-line options.
+
+**-v, --version**
+: Display version information.
+
+**-V, --verbose**
+: Set log level to DEBUG (default is INFO).
+
+**-C, --clear-cache**
+: Clear image cache and exit.
+
+**-q, --quiet**
+: Suppress log output.
+
+**-d, --append-dir** _dir_
+: Append an additional wallpaper search directory.
+
+This option can be provided multiple times.
+
+**-c, --config-file** _file_
+: Use a custom configuration file.
+
+**-D, --disable-actions**
+: Disable actions defined in the configuration file.
+
+**-a, --apply** _file_
+: Apply the specified image as wallpaper and exit.
+
+In this mode, the configuration is still parsed. Action placeholders are resolved
+from the selected image and any captured state values.
+
+# BEHAVIOR NOTES
+
+- CLI options are generally optional; configuration is the preferred customization path.
+- Some options are mutually exclusive (for example `--verbose` and `--quiet`).
+- With `--apply`, WallReel executes configured selection actions without opening the UI.
+
+# FILES
+
+`~/.config/wallreel/config.json`
+: Default configuration file location.
+
+`~/.cache/wallreel/`
+: Runtime cache location.
+
+# EXAMPLES
+
+Run with default configuration:
+
+```bash
+wallreel
+```
+
+Use a custom configuration file:
+
+```bash
+wallreel --config-file ~/.config/wallreel/config.json
+```
+
+Append additional search directories:
+
+```bash
+wallreel --append-dir ~/Pictures/Wallpapers --append-dir ~/Art
+```
+
+Apply a wallpaper and exit:
+
+```bash
+wallreel --apply ~/Pictures/wallpaper.jpg
+```
+
+# EXIT STATUS
+
+Returns `0` on success. Returns a non-zero value on failure.
+
+# SEE ALSO
+
+**wallreel**(5)
+
+# AUTHOR
+
+Uyanide <github.com/Uyanide>

docs/man/man.5.md

@@ -0,0 +1,233 @@
+---
+title: WALLREEL
+section: 5
+header: File Formats Manual
+footer: WallReel 2.0.1
+date: 2026-03-24
+---
+
+# NAME
+
+wallreel-config - configuration format for wallreel
+
+# SYNOPSIS
+
+`~/.config/wallreel/config.json`
+
+# DESCRIPTION
+
+WallReel reads configuration from a JSON document. The root object is divided into
+five sections:
+
+- `wallpaper`
+- `theme`
+- `action`
+- `style`
+- `cache`
+
+For complete machine-readable validation details, refer to `config.schema.json`.
+
+# WALLPAPER SECTION
+
+Defines where WallReel looks for images and what to exclude.
+
+If both `paths` and `dirs` are empty or omitted, WallReel defaults to recursively
+scanning the user's Pictures directory and treating all supported image files as
+wallpaper candidates.
+
+`paths` (array of string, default: `[]`)
+: Exact paths to specific image files.
+
+`dirs` (array of object, default: `[]`)
+: Directories to scan for images.
+
+Each item has:
+
+- `path` (string)
+- `recursive` (boolean)
+
+`excludes` (array of string, default: `[]`)
+: Exclude patterns as regular expressions.
+
+# THEME SECTION
+
+Configures color palettes.
+
+A dominant color is extracted from each wallpaper. If a palette is selected,
+WallReel picks the closest palette color as the primary color.
+
+`palettes` (array of object, default: `[]`)
+: Custom palette definitions.
+
+Each palette has:
+
+- `name` (string)
+- `colors` (array)
+
+Each color item has:
+
+- `name` (string)
+- `value` (hex string, for example `"#89b4fa"`)
+
+# ACTION SECTION
+
+Configures commands executed for preview, selection, and restore behavior.
+
+`previewDebounceTime` (integer, default: `300`)
+: Debounce interval in milliseconds for preview actions.
+
+`printSelected` (boolean, default: `true`)
+: Print selected wallpaper path to stdout on confirmation.
+
+`printPreview` (boolean, default: `false`)
+: Print previewed wallpaper path to stdout on preview.
+
+`onSelected` (string, default: `""`)
+: Command executed when a wallpaper is confirmed.
+
+`onPreview` (string, default: `""`)
+: Command executed when a wallpaper is previewed.
+
+`saveState` (array of object, default: `[]`)
+: Commands for capturing system values before changing wallpaper.
+
+Each item has:
+
+- `key` (placeholder key)
+- `fallback` (default value)
+- `command` (stdout-mapped command)
+- `timeout` (milliseconds)
+
+`onRestore` (string, default: `""`)
+: Command executed on restore. Saved state keys are usable as placeholders.
+
+`quitOnSelected` (boolean, default: `false`)
+: Exit application immediately after confirming a selection.
+
+`restoreOnClose` (boolean, default: `true`)
+: Run `onRestore` when application closes without a final selection.
+
+## ACTION PLACEHOLDERS
+
+The following placeholders are available in `onSelected`, `onPreview`, and
+`onRestore` (where applicable):
+
+`{{ path }}`
+: Full path of selected or previewed wallpaper.
+
+`{{ name }}`
+: File name of selected or previewed wallpaper.
+
+`{{ size }}`
+: Size in bytes of selected or previewed wallpaper.
+
+`{{ palette }}`
+: Selected palette name (`"null"` if none).
+
+`{{ colorName }}`
+: Chosen primary color name (`"null"` if none).
+
+`{{ colorHex }}`
+: Chosen primary color hex (`"null"` if none).
+
+`{{ domColorHex }}`
+: Dominant color hex extracted from the wallpaper.
+
+`{{ <key> }}`
+: Value of a saved state item with matching key.
+
+# STYLE SECTION
+
+Controls window layout and thumbnail dimensions.
+
+`image_width` (integer, default: `320`)
+: Width of each thumbnail.
+
+`image_height` (integer, default: `180`)
+: Height of each thumbnail.
+
+`image_focus_scale` (number, default: `1.5`)
+: Focus scale multiplier for highlighted thumbnail.
+
+`window_width` (integer, default: `750`)
+: Initial window width.
+
+`window_height` (integer, default: `500`)
+: Initial window height.
+
+# CACHE SECTION
+
+Controls persisted UI state.
+
+`saveSortMethod` (boolean, default: `true`)
+: Persist sort method and direction.
+
+`savePalette` (boolean, default: `true`)
+: Persist selected palette.
+
+`maxImageEntries` (integer, default: `1000`)
+: Maximum number of image cache entries. Older entries are evicted.
+
+# EXAMPLE
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/Uyanide/WallReel/refs/heads/master/config.schema.json",
+  "wallpaper": {
+    "paths": ["/home/user/Pictures/favorite.jpg"],
+    "dirs": [
+      {
+        "path": "/home/user/Pictures/Wallpapers",
+        "recursive": true
+      }
+    ],
+    "excludes": ["\\.gif$"]
+  },
+  "theme": {
+    "palettes": [
+      {
+        "name": "Dark",
+        "colors": [
+          { "name": "blue", "value": "#89b4fa" },
+          { "name": "red", "value": "#f38ba8" }
+        ]
+      }
+    ]
+  },
+  "action": {
+    "previewDebounceTime": 500,
+    "quitOnSelected": true,
+    "onPreview": "swww img {{ path }}",
+    "onSelected": "cp {{ path }} ~/.config/wallpaper/current/ && swww img {{ path }}",
+    "saveState": [
+      {
+        "key": "current_wp",
+        "fallback": "/home/user/Pictures/default.jpg",
+        "command": "find ~/.config/wallpaper/current -type f | head -n 1",
+        "timeout": 1000
+      }
+    ],
+    "onRestore": "swww img {{ current_wp }}"
+  },
+  "style": {
+    "image_width": 640,
+    "image_height": 400,
+    "image_focus_scale": 1.2,
+    "window_width": 1280,
+    "window_height": 720
+  },
+  "cache": {
+    "saveSortMethod": true,
+    "savePalette": true,
+    "maxImageEntries": 300
+  }
+}
+```
+
+# SEE ALSO
+
+**wallreel**(1)
+
+# AUTHOR
+
+Uyanide <github.com/Uyanide>