From c0465c7f2690dc9a1cda2f9857146152d90af915 Mon Sep 17 00:00:00 2001
From: Giovanni Harting <539@idlegandalf.com>
Date: Sat, 8 Nov 2025 22:46:42 +0100
Subject: [PATCH] chore: enforce config placement

---
 AGENTS.md               |  2 ++
 scripts/ac-power.lua    | 10 ++++++----
 scripts/kb-blackout.lua | 12 +++++++-----
 3 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7cd2926..75e5d8a 100644
--- a/AGENTS.md
+++ b/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`).
 
diff --git a/scripts/ac-power.lua b/scripts/ac-power.lua
index e6ababa..834cb5f 100644
--- a/scripts/ac-power.lua
+++ b/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
diff --git a/scripts/kb-blackout.lua b/scripts/kb-blackout.lua
index aab2fcf..624c0d2 100644
--- a/scripts/kb-blackout.lua
+++ b/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