chore: enforce config placement

AGENTS.md

@@ -7,6 +7,8 @@
 ## Layout & Conventions
 - `scripts/` — every Lua script lives here; filenames stay unique and map 1:1 to `script-name` values.
 - `scripts/<name>.lua` — script headers must summarize behavior, configuration, and dependencies because per-script AGENTS docs were removed.
+- Script structure stays predictable: the configuration block (e.g., `local config = {}` or equivalent) follows immediately after the header comment so future editors can adjust settings without scanning the rest of the file.
+- Add a short note near the config block clarifying that edits below that block are not required unless someone explicitly wants to modify behavior; this reassures casual users that they can stop there.
 - Root configs (`.luacheckrc`, `stylua.toml`) apply to the entire tree; do not duplicate them inside subdirectories.
 - Tests, fixtures, or helper assets should be placed alongside the script that depends on them using clear suffixes (e.g., `*_spec.lua`).
 

scripts/ac-power.lua

@@ -10,10 +10,6 @@
     Edit the CONFIG table below to match your Home Assistant deployment; the script ignores script-opts files.
 ]]
 
-local mp = require("mp")
-local utils = require("mp.utils")
-local msg = require("mp.msg")
-
 local CONFIG = {
   sensor_id = "sensor.ac_power", -- Home Assistant entity id
   ha_base_url = "http://homeassistant.local:8123",
@@ -35,6 +31,12 @@ local CONFIG = {
   initial_message_duration = 0, -- 0 keeps OSD up until refreshed
 }
 
+-- No edits are required below unless you want to change script behavior.
+
+local mp = require("mp")
+local utils = require("mp.utils")
+local msg = require("mp.msg")
+
 local last_watts
 local last_display_ts = 0
 local last_unit

scripts/kb-blackout.lua

@@ -14,11 +14,6 @@
     Edit the `config` table below to tune timeouts, restore behavior, minimum brightness, LED device detection, and the `brightnessctl` binary path.
 ]]
 
-local mp = require("mp")
-local msg = require("mp.msg")
-local utils = require("mp.utils")
-local jit = rawget(_G, "jit")
-
 local config = {
   timeout_ms = 3000,
   restore_on_pause = true,
@@ -28,6 +23,13 @@ local config = {
   brightnessctl_path = "brightnessctl",
 }
 
+-- No edits are required below unless you want to change script behavior.
+
+local mp = require("mp")
+local msg = require("mp.msg")
+local utils = require("mp.utils")
+local jit = rawget(_G, "jit")
+
 local function coerce_boolean(value, default)
   if type(value) == "boolean" then
     return value