diff --git a/scripts/kb-blackout.lua b/scripts/kb-blackout.lua
index ad6822c..aab2fcf 100644
--- a/scripts/kb-blackout.lua
+++ b/scripts/kb-blackout.lua
@@ -1,19 +1,17 @@
 --[[
-script-name=kb-blackout
-script-description=Dims (or disables) the keyboard backlight while mpv plays media.
+  kb-blackout.lua - dims (or disables) the keyboard backlight while mpv is playing.
 
-Behaviors:
-  * Observes pause/playback/core-idle properties to decide when to dim or restore, cancelling pending timers once playback stops.
-  * Stores the original brightness level per session and uses `brightnessctl` exclusively for both detection and control so permissions stay centralized.
-  * Debounces rapid toggles, auto-detects LED devices when possible, and warns when Linux platform, device path, or privileges do not satisfy the requirements.
+  Features:
+    * Listens to pause/playback/core-idle so lights only stay off when media is actively playing.
+    * Captures the session's starting brightness, dims via `brightnessctl`, and restores exactly that value when playback stops.
+    * Debounces rapid state flips, auto-discovers an LED device (`brightnessctl --list`), and surfaces warnings when Linux, device, or permission prerequisites fail.
 
-Configuration (edit values here):
-  timeout_ms = 3000          -- delay after playback resumes before lights turn off
-  restore_on_pause = true    -- immediately restore while paused
-  minimum_brightness = 0     -- fallback value if hardware rejects zero (use integer >= 0)
-  led_path = ""              -- optional brightnessctl device override (see `brightnessctl --list`)
-  debounce_ms = 250          -- suppress duplicate intents within this window
-  brightnessctl_path = "brightnessctl" -- path to brightnessctl binary
+  Requirements:
+    * Linux + mpv 0.36+ with the bundled Lua 5.2 runtime.
+    * `brightnessctl` accessible in PATH or via `brightnessctl_path`, with permission to control the target LED class device.
+
+  Configuration:
+    Edit the `config` table below to tune timeouts, restore behavior, minimum brightness, LED device detection, and the `brightnessctl` binary path.
 ]]
 
 local mp = require("mp")