diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -148,6 +148,7 @@ Prerequisites:
 - Node.js 24+, then `npm ci` (the UI's TypeScript compiler and test DOM)
 - `cargo install tauri-cli --version "^2"`
 - Xcode CLT on macOS
+- On Linux: `webkit2gtk-4.1` and `libayatana-appindicator` (Arch package names)
 - `gh auth login`, or a token in the config
 
 ```sh
@@ -160,5 +161,12 @@ make snapshot   # fetch once, print a table, write ui/dev-snapshot.json
 make preview    # serve ui/ in a browser against that snapshot (no Tauri needed)
 ```
 
+On Linux, `make install`, `make bundle` and `make uninstall` don't apply (they
+are macOS-specific): use `make run`, or `cargo tauri build` in
+`crates/craft-status-app` for an AppImage, .deb or .rpm. The app sets
+`WEBKIT_DMABUF_RENDERER_FORCE_SHM=1` at startup, because WebKitGTK's GPU
+buffers crash or half-paint the transparent window on some Wayland setups
+(seen on NVIDIA).
+
 To start the app at login, `make install` adds
 `~/Library/LaunchAgents/ai.storyteller.craft-status.plist`.
diff --git a/crates/craft-status-app/src/main.rs b/crates/craft-status-app/src/main.rs
--- a/crates/craft-status-app/src/main.rs
+++ b/crates/craft-status-app/src/main.rs
@@ -2,5 +2,12 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
 fn main() {
+    // WebKitGTK's GPU (dmabuf) buffers break the transparent window on some
+    // Wayland setups (NVIDIA): a protocol error at launch, or only the changed
+    // regions get painted. Shared-memory buffers fix both. Set it to 0 to opt out.
+    #[cfg(target_os = "linux")]
+    if std::env::var_os("WEBKIT_DMABUF_RENDERER_FORCE_SHM").is_none() {
+        std::env::set_var("WEBKIT_DMABUF_RENDERER_FORCE_SHM", "1");
+    }
     craft_status_app_lib::run()
 }