Add detailed comments to script and comprehensive README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Omarchy_resolve_v2.sh

@@ -1,18 +1,47 @@
 #!/usr/bin/env bash
-# DaVinci Resolve installer for Omarchy/Arch — one-shot, self-healing, ABI-safe
+# ==============================================================================
-# - ZIP already in ~/Downloads/
+# DaVinci Resolve Installer for Omarchy (Arch Linux + Hyprland + NVIDIA)
-# - Assumes NVIDIA drivers are already installed and working
+#
-# - Extracts in ~/Downloads, minimal validation, AUR-style unbundling (glib/gio/gmodule only), RPATH patch
+# DaVinci Resolve is a professional video editing suite by Blackmagic Design.
-# - Installs system desktop files & icons, creates wrapper, rewires system desktop
+# It's distributed as a self-extracting AppImage-style .run file inside a ZIP.
-# - Creates a user .desktop pointing to the wrapper (Hyprland-friendly)
+# This script automates the entire installation process on Omarchy, handling
-# - Leaves vendor libc++/libc++abi in place (prevents ABI breakage)
+# all the quirks and workarounds needed to get Resolve running on Arch Linux.
-# - Ensures legacy libcrypt.so.1 via libxcrypt-compat + fallback symlink
+#
+# Why this script exists:
+#   Resolve is built for CentOS/RHEL and bundles its own versions of many
+#   libraries. On Arch Linux, some of these bundled libraries conflict with
+#   system libraries (especially glib), while others (libc++, libc++abi)
+#   MUST be kept because Resolve was compiled against specific ABI versions.
+#   Getting this balance right is tricky — this script handles it automatically.
+#
+# What this script does:
+#   1. Finds the Resolve ZIP in ~/Downloads/
+#   2. Installs system dependencies (codecs, GPU libs, legacy compat libs)
+#   3. Extracts the ZIP → .run → squashfs-root (AppImage payload)
+#   4. Replaces bundled glib/gio/gmodule with system versions (ABI-safe)
+#   5. Keeps vendor libc++/libc++abi (removing these breaks Resolve)
+#   6. Installs to /opt/resolve with RPATH patching for all ELF binaries
+#   7. Ensures legacy libcrypt.so.1 is available (Arch dropped it)
+#   8. Installs desktop entries, icons, and udev rules
+#   9. Creates an XWayland wrapper script for Hyprland compatibility
+#
+# Prerequisites:
+#   - Omarchy (Arch Linux) with NVIDIA drivers installed and working
+#   - DaVinci Resolve Linux ZIP downloaded to ~/Downloads/
+#   - Internet connection (for installing packages)
+# ==============================================================================
 
 set -euo pipefail
+
+# Logging helpers with visual indicators for easy scanning of output
 log(){ echo -e "▶ $*"; }
 warn(){ echo -e "⚠️  $*" >&2; }
 err(){ echo -e "❌ $*" >&2; exit 1; }
 
+# Find the Resolve ZIP file in ~/Downloads/. The user must download it
+# manually from https://www.blackmagicdesign.com/products/davinciresolve
+# because Blackmagic requires filling out a form (no direct download link).
+# If multiple ZIPs exist (e.g. different versions), we use the newest one.
 ZIP_DIR="${HOME}/Downloads"
 shopt -s nullglob
 ZIP_FILES=("${ZIP_DIR}"/DaVinci_Resolve*_Linux.zip)
@@ -25,8 +54,13 @@ RESOLVE_ZIP="$(ls -1t "${ZIP_FILES[@]}" 2>/dev/null | head -n1)"
 [[ -n "${RESOLVE_ZIP}" ]] || err "Could not determine newest ZIP file"
 log "Using installer ZIP: ${RESOLVE_ZIP}"
 
-# ---------------- Packages ----------------
+# ==================== Package Installation ====================
-# Opt-in full system upgrade (can be slow and may update kernel/NVIDIA stack unexpectedly)
+#
+# System upgrade is opt-in because a full -Syu can update the kernel or
+# NVIDIA driver stack, which might break things or require a reboot in
+# the middle of the install. Set RESOLVE_FULL_UPGRADE=1 if you want it.
+# Otherwise we just sync the package database (-Sy) so pacman knows
+# what's available without actually upgrading anything.
 if [[ "${RESOLVE_FULL_UPGRADE:-0}" == "1" ]]; then
   log "Updating system packages (RESOLVE_FULL_UPGRADE=1)..."
   sudo pacman -Syu --noconfirm
@@ -35,28 +69,57 @@ else
   # Just sync package database without upgrading
   sudo pacman -Sy --noconfirm
 fi
+# Build/extraction tools:
+#   unzip:              Extracts the Resolve ZIP archive
+#   patchelf:           Modifies RPATH in ELF binaries (tells them where to find libs)
+#   libarchive:         Archive handling library (dependency for extraction)
+#   xdg-user-dirs:      Ensures standard user directories exist (~/Downloads, etc.)
+#   desktop-file-utils: Provides update-desktop-database for app menu integration
+#   file:               Identifies file types (used to find ELF binaries for patching)
+#   gtk-update-icon-cache: Refreshes the icon cache so Resolve's icon appears
 log "Installing required tools..."
 if ! sudo pacman -S --needed --noconfirm unzip patchelf libarchive xdg-user-dirs desktop-file-utils file gtk-update-icon-cache; then
   warn "Some optional tools failed to install, continuing anyway..."
 fi
 
-# Runtime bits (KEEP vendor libc++/libc++abi)
+# Runtime dependencies that Resolve needs but doesn't bundle:
+#   libxcrypt-compat:   Provides legacy libcrypt.so.1 (Arch moved to libxcrypt v2)
+#   ffmpeg4.4:          Older FFmpeg version that Resolve links against
+#   glu:                OpenGL Utility Library (3D rendering support)
+#   gtk2:               GTK2 toolkit (Resolve's UI uses some GTK2 components)
+#   fuse2:              Filesystem in Userspace v2 (for AppImage compatibility)
+#
+# IMPORTANT: We deliberately do NOT replace Resolve's bundled libc++/libc++abi
+# with system versions. Resolve was compiled against specific C++ ABI versions
+# and swapping them causes crashes. Only glib/gio/gmodule get replaced (later).
 log "Installing runtime dependencies..."
 if ! sudo pacman -S --needed --noconfirm libxcrypt-compat ffmpeg4.4 glu gtk2 fuse2; then
   warn "Some runtime dependencies failed to install (may affect functionality)"
 fi
 
-# TLS path for extras downloader
+# Resolve's built-in extras downloader expects TLS certificates at the
+# Red Hat/CentOS path (/etc/pki/tls) rather than the Arch path (/etc/ssl).
+# This symlink lets it find the system certificates.
 if [[ ! -e /etc/pki/tls ]]; then
   sudo mkdir -p /etc/pki
   sudo ln -sf /etc/ssl /etc/pki/tls
 fi
 
-# ---------------- Extract in Downloads ----------------
+# ==================== Extraction ====================
+#
+# The Resolve download is a ZIP containing a .run file. The .run file is a
+# self-extracting AppImage-style archive containing a squashfs filesystem.
+# We extract it in stages: ZIP → .run → squashfs-root (the actual app files).
+#
+# This needs about 10GB of free space for the temporary extraction.
+# Everything is cleaned up automatically when the script exits (via trap).
 NEEDED_GB=10
 FREE_KB=$(df --output=avail -k "${ZIP_DIR}" | tail -n1); FREE_GB=$((FREE_KB/1024/1024))
 (( FREE_GB >= NEEDED_GB )) || err "Not enough free space in ${ZIP_DIR}: ${FREE_GB} GiB < ${NEEDED_GB} GiB"
 
+# Create a temporary directory for extraction. Using mktemp ensures a unique
+# name so multiple runs don't conflict. The cleanup trap removes it when the
+# script exits (whether it succeeds, fails, or is interrupted with Ctrl+C).
 WORKDIR="$(mktemp -d -p "${ZIP_DIR}" .resolve-extract-XXXXXXXX)"
 cleanup() {
   if [[ -n "${WORKDIR:-}" && -d "${WORKDIR}" ]]; then
@@ -68,6 +131,9 @@ trap cleanup EXIT
 log "Unpacking ZIP to ${WORKDIR}…"
 unzip -q "${RESOLVE_ZIP}" -d "${WORKDIR}"
 
+# Find the .run installer inside the extracted ZIP. It's a self-extracting
+# archive that contains the actual application files in a squashfs image.
+# --appimage-extract tells it to just extract without trying to run anything.
 RUN_FILE="$(find "${WORKDIR}" -maxdepth 2 -type f -name 'DaVinci_Resolve_*_Linux.run' | head -n1 || true)"
 [[ -n "${RUN_FILE}" ]] || err "Could not find the .run installer in the ZIP"
 chmod +x "${RUN_FILE}"
@@ -86,8 +152,23 @@ chmod -R u+rwX,go+rX,go-w "${APPDIR}" || warn "Could not normalize all permissio
 # Minimal validation
 [[ -s "${APPDIR}/bin/resolve" ]] || err "resolve binary missing or zero-size"
 
-# ---------------- AUR-style niceties (ABI-safe) ----------------
+# ==================== ABI-Safe Library Replacement ====================
-# IMPORTANT: Do NOT touch vendor libc++/libc++abi. Only swap glib/gio/gmodule to system libs.
+#
+# This is the most delicate part of the install. Resolve bundles its own
+# copies of many libraries, but some of them are too old for Arch and cause
+# crashes or segfaults. The trick is knowing WHICH ones to replace:
+#
+# REPLACE with system versions (these are safe to swap):
+#   - libglib-2.0.so.0    — GLib core library
+#   - libgio-2.0.so.0     — GLib I/O library
+#   - libgmodule-2.0.so.0 — GLib module loading
+#   These are stable C libraries with a very consistent ABI.
+#
+# KEEP bundled versions (replacing these breaks Resolve):
+#   - libc++.so           — C++ standard library (LLVM)
+#   - libc++abi.so         — C++ ABI support library
+#   Resolve was compiled with a specific libc++ version. Using the system
+#   version causes ABI mismatches and immediate crashes.
 pushd "${APPDIR}" >/dev/null
 
 # Verify system libraries exist before replacing bundled ones
@@ -106,7 +187,10 @@ for syslib in "${!GLIB_LIBS[@]}"; do
   fi
 done
 
-# Panels -> libs/ (best-effort)
+# Extract DaVinci control panel libraries from a bundled tarball and move
+# them into the main libs/ directory so they're found at runtime. These
+# support Blackmagic's hardware control surfaces (DaVinci Resolve Editor
+# Keyboard, Mini Panel, Micro Panel, etc.).
 if [[ -d "share/panels" ]]; then
   pushd "share/panels" >/dev/null
   tar -zxf dvpanel-framework-linux-x86_64.tgz 2>/dev/null || true
@@ -118,13 +202,20 @@ if [[ -d "share/panels" ]]; then
   popd >/dev/null
 fi
 
+# Clean up AppImage launcher files and installer leftovers — we don't need
+# them since we're installing to /opt/resolve directly, not running as an AppImage.
 rm -f "AppRun" "AppRun*" 2>/dev/null || true
 rm -rf "installer" "installer*" 2>/dev/null || true
 mkdir -p "bin"
 ln -sf "../BlackmagicRAWPlayer/BlackmagicRawAPI" "bin/" 2>/dev/null || true
 popd >/dev/null
 
-# ---------------- Install to /opt/resolve ----------------
+# ==================== Install to /opt/resolve ====================
+#
+# Copy the extracted application to its final location. /opt/ is the
+# standard Linux directory for third-party software that doesn't come
+# from the package manager. Using rsync (if available) is faster for
+# re-installs because it only copies changed files.
 log "Installing Resolve to /opt/resolve…"
 sudo rm -rf /opt/resolve
 sudo mkdir -p /opt/resolve
@@ -135,9 +226,18 @@ else
 fi
 sudo mkdir -p /opt/resolve/.license
 
-# RPATH patch - done AFTER installation to /opt/resolve
+# RPATH Patching
-# NOTE: No size limit - large libs like libQt5WebEngineCore.so (~200M) must also be patched
+#
-# to avoid mixed RPATH issues where some libs search old AppImage paths
+# RPATH is a field inside ELF binaries that tells the dynamic linker where
+# to search for shared libraries. Resolve's binaries have RPATHs pointing
+# to the original AppImage extraction paths, which don't exist anymore.
+#
+# We patch EVERY ELF binary (executables and shared objects) to search
+# /opt/resolve/libs/ and all its subdirectories. This includes large files
+# like libQt5WebEngineCore.so (~200MB) — skipping them causes "library not
+# found" errors because they link to other Resolve libs.
+#
+# This step can take a minute or two due to the number of files.
 log "Applying RPATH with patchelf (this may take a while for large libraries)…"
 RPATH_DIRS=( "libs" "libs/plugins/sqldrivers" "libs/plugins/xcbglintegrations" "libs/plugins/imageformats"
              "libs/plugins/platforms" "libs/Fusion" "plugins" "bin"
@@ -188,14 +288,24 @@ else
   warn "patchelf not found, skipping RPATH patching"
 fi
 
-# --- Ensure legacy libcrypt is available (Arch fix for Resolve) -------------
+# Legacy libcrypt Fix
+#
+# Arch Linux moved from libcrypt.so.1 to libcrypt.so.2 (via libxcrypt).
+# Resolve still links against the old .so.1 version. libxcrypt-compat
+# provides it, and we symlink it into Resolve's libs directory as a
+# fallback in case the system-wide version isn't found in the search path.
 sudo pacman -S --needed --noconfirm libxcrypt-compat || true
 sudo ldconfig || true
 if [[ -e /usr/lib/libcrypt.so.1 ]]; then
   sudo ln -sf /usr/lib/libcrypt.so.1 /opt/resolve/libs/libcrypt.so.1
 fi
 
-# ---------------- Desktop, icons, udev (system) ----------------
+# ==================== Desktop Integration ====================
+#
+# Install .desktop files (app menu entries), icons, and udev rules so
+# Resolve integrates properly with the desktop environment. The .desktop
+# files go to /usr/share/applications/ (system-wide) and icons go to
+# the hicolor icon theme at standard sizes.
 log "Installing desktop entries and icons..."
 declare -A DESKTOP_FILES=(
   ["/opt/resolve/share/DaVinciResolve.desktop"]="/usr/share/applications/DaVinciResolve.desktop"
@@ -231,7 +341,9 @@ done
 sudo update-desktop-database >/dev/null 2>&1 || true
 sudo gtk-update-icon-cache -f /usr/share/icons/hicolor >/dev/null 2>&1 || true
 
-# udev rules
+# Udev rules — these give Resolve permission to access Blackmagic hardware
+# devices (capture cards, control panels, editing keyboards) without root.
+# Without these rules, the devices would only be accessible as root.
 for r in 99-BlackmagicDevices.rules 99-ResolveKeyboardHID.rules 99-DavinciPanel.rules; do
   if [[ -f "/opt/resolve/share/etc/udev/rules.d/${r}" ]]; then
     sudo install -D -m 0644 "/opt/resolve/share/etc/udev/rules.d/${r}" "/usr/lib/udev/rules.d/${r}"
@@ -239,7 +351,21 @@ for r in 99-BlackmagicDevices.rules 99-ResolveKeyboardHID.rules 99-DavinciPanel.
 done
 sudo udevadm control --reload-rules && sudo udevadm trigger || true
 
-# ---------------- Wrapper + helper ----------------
+# ==================== XWayland Wrapper Script ====================
+#
+# DaVinci Resolve does NOT support native Wayland — it only works under
+# X11 or XWayland. Hyprland (Omarchy's compositor) provides XWayland
+# compatibility, but Resolve needs to be told to use it explicitly.
+#
+# This wrapper script:
+#   1. Clears stale Qt lockfiles that can prevent Resolve from starting
+#      (happens when Resolve crashes or is killed without clean shutdown)
+#   2. Forces QT_QPA_PLATFORM=xcb (tells Qt to use X11/XWayland, not Wayland)
+#   3. Enables Qt's auto screen scaling for HiDPI displays
+#   4. Launches the actual Resolve binary
+#
+# For hybrid NVIDIA laptops (Optimus), you can uncomment the PRIME render
+# offload lines to force Resolve onto the discrete GPU.
 cat << 'EOF' | sudo tee /usr/local/bin/resolve-nvidia-open >/dev/null
 #!/usr/bin/env bash
 set -euo pipefail
@@ -259,6 +385,9 @@ exec /opt/resolve/bin/resolve "$@"
 EOF
 sudo chmod +x /usr/local/bin/resolve-nvidia-open
 
+# Create a convenience symlink at /usr/bin/davinci-resolve so users can
+# launch Resolve by typing "davinci-resolve" in any terminal. Points to
+# the wrapper script so XWayland settings are always applied.
 if [[ ! -e /usr/bin/davinci-resolve ]]; then
   if [[ -x /usr/local/bin/resolve-nvidia-open ]]; then
     echo -e '#!/usr/bin/env bash\nexec /usr/local/bin/resolve-nvidia-open "$@"' | sudo tee /usr/bin/davinci-resolve >/dev/null
@@ -268,7 +397,9 @@ if [[ ! -e /usr/bin/davinci-resolve ]]; then
   sudo chmod +x /usr/bin/davinci-resolve
 fi
 
-# Point system desktop launchers at the wrapper
+# Update the system .desktop files to use our wrapper instead of launching
+# Resolve directly. This ensures XWayland mode is always used regardless
+# of how Resolve is launched (app menu, file association, etc.).
 WRAPPER="/usr/local/bin/resolve-nvidia-open"
 if [[ -f /usr/share/applications/DaVinciResolve.desktop ]]; then
   sudo sed -i "s|^Exec=.*|Exec=${WRAPPER} %U|" /usr/share/applications/DaVinciResolve.desktop
@@ -278,7 +409,11 @@ if [[ -f /usr/share/applications/DaVinciResolveCaptureLogs.desktop ]]; then
 fi
 sudo update-desktop-database >/dev/null 2>&1 || true
 
-# ---------------- User-level desktop entry (takes precedence) ----------------
+# Create a user-level .desktop entry in ~/.local/share/applications/.
+# User-level entries take precedence over system-level ones, so this
+# ensures the wrapper is always used even if a system update overwrites
+# the system .desktop file. Also sets StartupWMClass=resolve so Hyprland
+# can properly identify the window for window rules and taskbar grouping.
 mkdir -p "${HOME}/.local/share/applications"
 cat > "${HOME}/.local/share/applications/davinci-resolve-wrapper.desktop" << EOF
 [Desktop Entry]

README.md

@@ -0,0 +1,244 @@
+# DaVinci Resolve - Omarchy
+
+Install [DaVinci Resolve](https://www.blackmagicdesign.com/products/davinciresolve) on [Omarchy](https://omarchy.com) (Arch Linux + Hyprland) with NVIDIA GPU support.
+
+Handles all the compatibility quirks of running Resolve on Arch Linux — library conflicts, XWayland setup, RPATH patching, and legacy library shims — so you don't have to.
+
+## Requirements
+
+- **OS**: [Omarchy](https://omarchy.com) (Arch Linux)
+- **GPU**: NVIDIA with proprietary drivers installed and working
+- **Disk space**: ~10GB free in ~/Downloads for extraction (temporary)
+- **DaVinci Resolve ZIP**: Downloaded from Blackmagic's website
+
+## Quick Start
+
+1. **Download DaVinci Resolve** from [blackmagicdesign.com](https://www.blackmagicdesign.com/products/davinciresolve)
+   - Choose "DaVinci Resolve" (free) or "DaVinci Resolve Studio" (paid)
+   - Select **Linux** and download the ZIP file
+   - Save it to `~/Downloads/`
+
+2. **Run the installer**:
+```bash
+git clone https://github.com/28allday/DaVinci-Resolve-Omarchy.git
+cd DaVinci-Resolve-Omarchy
+chmod +x Omarchy_resolve_v2.sh
+./Omarchy_resolve_v2.sh
+```
+
+3. **Launch Resolve** from your app menu or run `resolve-nvidia-open`
+
+## What It Does
+
+### 1. Installs Dependencies
+
+**Build/extraction tools:**
+
+| Package | Purpose |
+|---------|---------|
+| `unzip` | Extracts the Resolve ZIP archive |
+| `patchelf` | Modifies library search paths (RPATH) in binaries |
+| `libarchive` | Archive handling library |
+| `desktop-file-utils` | App menu integration |
+| `file` | Identifies ELF binaries for RPATH patching |
+
+**Runtime dependencies:**
+
+| Package | Purpose |
+|---------|---------|
+| `libxcrypt-compat` | Provides legacy `libcrypt.so.1` (Arch dropped it) |
+| `ffmpeg4.4` | Older FFmpeg version that Resolve links against |
+| `glu` | OpenGL Utility Library for 3D rendering |
+| `gtk2` | GTK2 toolkit (some Resolve UI components use it) |
+| `fuse2` | AppImage compatibility layer |
+
+### 2. Extracts Resolve
+
+The download is a ZIP containing a `.run` file (self-extracting AppImage). The script unpacks it in stages:
+
+```
+ZIP → .run file → squashfs-root (actual application files)
+```
+
+Temporary files are cleaned up automatically when the script finishes.
+
+### 3. Handles Library Conflicts (ABI-Safe)
+
+This is the tricky part. Resolve bundles its own libraries, but some conflict with Arch's newer versions:
+
+| Library | Action | Why |
+|---------|--------|-----|
+| `libglib-2.0.so` | **Replace** with system | Stable C ABI, safe to swap |
+| `libgio-2.0.so` | **Replace** with system | Stable C ABI, safe to swap |
+| `libgmodule-2.0.so` | **Replace** with system | Stable C ABI, safe to swap |
+| `libc++.so` | **Keep** bundled | C++ ABI mismatch causes crashes |
+| `libc++abi.so` | **Keep** bundled | C++ ABI mismatch causes crashes |
+
+### 4. Patches RPATH
+
+Every ELF binary in Resolve gets its RPATH patched to point to `/opt/resolve/libs/` and subdirectories. Without this, binaries would look for libraries in the original AppImage paths that no longer exist.
+
+### 5. Creates XWayland Wrapper
+
+Resolve doesn't support native Wayland. The wrapper script (`resolve-nvidia-open`) forces XWayland mode by setting `QT_QPA_PLATFORM=xcb`, and also clears stale Qt lockfiles that can prevent Resolve from starting after a crash.
+
+### 6. Desktop Integration
+
+- Installs `.desktop` files for the app menu
+- Installs icons at proper hicolor sizes
+- Installs udev rules for Blackmagic hardware (capture cards, control panels)
+- Points all launchers at the XWayland wrapper
+
+## Files Installed
+
+### Application
+
+| Path | Purpose |
+|------|---------|
+| `/opt/resolve/` | Main application directory |
+| `/opt/resolve/bin/resolve` | Resolve binary |
+| `/opt/resolve/libs/` | Bundled libraries |
+
+### Scripts
+
+| Path | Purpose |
+|------|---------|
+| `/usr/local/bin/resolve-nvidia-open` | XWayland wrapper (main launcher) |
+| `/usr/bin/davinci-resolve` | Convenience symlink to wrapper |
+
+### Desktop Entries
+
+| Path | Purpose |
+|------|---------|
+| `/usr/share/applications/DaVinciResolve.desktop` | System app menu entry |
+| `~/.local/share/applications/davinci-resolve-wrapper.desktop` | User entry (takes priority) |
+
+### Icons
+
+| Path | Purpose |
+|------|---------|
+| `/usr/share/icons/hicolor/128x128/apps/davinci-resolve.png` | App icon |
+
+### Hardware Support
+
+| Path | Purpose |
+|------|---------|
+| `/usr/lib/udev/rules.d/99-BlackmagicDevices.rules` | Blackmagic capture cards |
+| `/usr/lib/udev/rules.d/99-ResolveKeyboardHID.rules` | Resolve Editor Keyboard |
+| `/usr/lib/udev/rules.d/99-DavinciPanel.rules` | DaVinci control panels |
+
+## Configuration
+
+### Full System Upgrade
+
+By default, the script syncs the package database without upgrading. To include a full system upgrade:
+
+```bash
+RESOLVE_FULL_UPGRADE=1 ./Omarchy_resolve_v2.sh
+```
+
+### Hybrid GPU Laptops (Optimus)
+
+If you have an Intel iGPU + NVIDIA dGPU, edit the wrapper to force Resolve onto the NVIDIA GPU:
+
+```bash
+sudo nano /usr/local/bin/resolve-nvidia-open
+```
+
+Uncomment these lines:
+```bash
+export __NV_PRIME_RENDER_OFFLOAD=1
+export __GLX_VENDOR_LIBRARY_NAME=nvidia
+```
+
+## Troubleshooting
+
+### Resolve won't start / crashes immediately
+
+- Check logs: `~/.local/share/DaVinciResolve/logs/ResolveDebug.txt`
+- Verify NVIDIA driver is working: `nvidia-smi`
+- Try launching from terminal to see errors: `resolve-nvidia-open`
+
+### "Cannot open display" error
+
+- Make sure XWayland is enabled in Hyprland (it is by default on Omarchy)
+- Check the wrapper is using xcb: `grep QT_QPA_PLATFORM /usr/local/bin/resolve-nvidia-open`
+
+### Resolve says "single instance already running"
+
+Stale lockfiles from a previous crash. The wrapper clears these automatically, but if it persists:
+
+```bash
+rm -f /tmp/qtsingleapp-DaVinci*
+```
+
+### Missing library errors
+
+Re-run the installer — it will re-patch RPATH and re-check dependencies:
+
+```bash
+./Omarchy_resolve_v2.sh
+```
+
+### GPU not detected / OpenCL errors
+
+- Ensure NVIDIA drivers are installed: `pacman -Qi nvidia-utils`
+- Check GPU is visible: `nvidia-smi`
+- Verify OpenCL: `pacman -S --needed opencl-nvidia`
+
+## Updating Resolve
+
+1. Download the new version ZIP from Blackmagic's website to `~/Downloads/`
+2. Run the installer again — it automatically picks the newest ZIP:
+
+```bash
+./Omarchy_resolve_v2.sh
+```
+
+The previous installation at `/opt/resolve` will be replaced.
+
+## Uninstalling
+
+```bash
+# Remove application
+sudo rm -rf /opt/resolve
+
+# Remove scripts
+sudo rm -f /usr/local/bin/resolve-nvidia-open
+sudo rm -f /usr/bin/davinci-resolve
+
+# Remove desktop entries
+sudo rm -f /usr/share/applications/DaVinciResolve.desktop
+sudo rm -f /usr/share/applications/DaVinciControlPanelsSetup.desktop
+sudo rm -f /usr/share/applications/blackmagicraw-player.desktop
+sudo rm -f /usr/share/applications/blackmagicraw-speedtest.desktop
+rm -f ~/.local/share/applications/davinci-resolve-wrapper.desktop
+
+# Remove icons
+sudo rm -f /usr/share/icons/hicolor/128x128/apps/davinci-resolve.png
+sudo rm -f /usr/share/icons/hicolor/128x128/apps/davinci-resolve-panels-setup.png
+sudo rm -f /usr/share/icons/hicolor/256x256/apps/blackmagicraw-player.png
+sudo rm -f /usr/share/icons/hicolor/256x256/apps/blackmagicraw-speedtest.png
+
+# Remove udev rules
+sudo rm -f /usr/lib/udev/rules.d/99-BlackmagicDevices.rules
+sudo rm -f /usr/lib/udev/rules.d/99-ResolveKeyboardHID.rules
+sudo rm -f /usr/lib/udev/rules.d/99-DavinciPanel.rules
+
+# Remove user data (WARNING: deletes all projects and settings)
+rm -rf ~/.local/share/DaVinciResolve
+
+# Update caches
+sudo update-desktop-database
+sudo gtk-update-icon-cache -f /usr/share/icons/hicolor
+```
+
+## Credits
+
+- [Omarchy](https://omarchy.com) - The Arch Linux distribution this was built for
+- [Blackmagic Design](https://www.blackmagicdesign.com/) - DaVinci Resolve
+- [Hyprland](https://hyprland.org/) - Wayland compositor (XWayland support)
+
+## License
+
+This project is provided as-is for the Omarchy community.