diff --git a/README.md b/README.md
index caade5f..d1fce05 100644
--- a/README.md
+++ b/README.md
@@ -81,8 +81,10 @@ Download a prebuilt installer from **[GitHub Releases](https://github.com/3xian/
 - macOS: Apple Silicon and Intel builds
 - Linux: build from source; CI installers are not available yet
 
-On Wayland (niri, Sway, Hyprland, …) WebKitGTK cannot composite a transparent
-window, and GTK client-side decorations render as a black bar. Launch with:
+On some Wayland compositors (niri, Sway, Hyprland, …) Overlay CSD and
+acrylic transparency mis-render with WebKitGTK. These flags are a
+workaround until that stack handles the default chrome; they can be
+dropped then. Launch with:
 
 ```bash
 PinkCode --disable-csd --disable-transparency
@@ -130,7 +132,7 @@ npm run check              # frontend + Rust (fmt/clippy/test) — same as CI
 | Flag | Meaning |
 |------|---------|
 | `--disable-csd` | Hide client-side decorations (black title bar on Wayland) |
-| `--disable-transparency` | Opaque window (WebKitGTK has no Wayland alpha protocol) |
+| `--disable-transparency` | Opaque window (WebKitGTK + compositor alpha) |
 | `-h`, `--help` | Show flags |
 
 ## Architecture
diff --git a/src-tauri/src/cli.rs b/src-tauri/src/cli.rs
index 9f733c0..b5a8314 100644
--- a/src-tauri/src/cli.rs
+++ b/src-tauri/src/cli.rs
@@ -1,9 +1,10 @@
 //! Startup flags for window chrome that must be applied before the webview exists.
 //!
-//! Acrylic + Overlay CSD is shaped for macOS/Windows. On Wayland, WebKitGTK
-//! cannot composite an alpha surface (no protocol support), and GTK CSD shows
-//! as a black bar. These flags rewrite `tauri.conf.json` window fields in
-//! memory so the window is created opaque and undecorated.
+//! Acrylic + Overlay CSD is shaped for macOS/Windows. On some Wayland
+//! compositors the same chrome mis-renders with WebKitGTK. These flags are a
+//! compatibility workaround: they rewrite `tauri.conf.json` window fields in
+//! memory so the window is created with `decorations=false` and
+//! `transparent=false`. Drop them when the stack handles the default chrome.
 
 use tauri::utils::config::{Color, WindowConfig};
 use tauri::TitleBarStyle;
@@ -20,8 +21,8 @@ Usage:
 Options:
   --disable-csd             Hide client-side decorations (fixes the black
                             title bar on Wayland compositors such as niri)
-  --disable-transparency    Opaque window (WebKitGTK has no Wayland
-                            protocol for alpha compositing)
+  --disable-transparency    Opaque window (WebKitGTK + compositor alpha
+                            on some Wayland setups)
   -h, --help                Show this help
 ";
 
@@ -37,8 +38,9 @@ pub enum Action {
 }
 
 impl Flags {
-    /// GTK reads `GTK_CSD` at init; `set_decorations(false)` after the window
-    /// exists is not enough to stop the black CSD bar.
+    /// GTK reads `GTK_CSD` at gtk_init. This only disables GTK's default CSD;
+    /// Tao still installs a custom titlebar. `decorations=false` in `apply()`
+    /// is what actually hides chrome.
     pub fn prepare_env(self) {
         if self.disable_csd {
             #[cfg(target_os = "linux")]