chore: add repo tooling

.luacheckrc

@@ -0,0 +1,16 @@
+std = "lua52"
+unused_args = false
+max_line_length = 120
+
+read_globals = {
+    "mp",
+    "mpv",
+}
+
+allow_defined_top = true
+
+files["**/*.lua"] = {
+    ignore = {
+        "631", -- allow string.format mismatch warnings common in mpv scripts
+    },
+}

AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS
+
+## Repository Purpose
+- Provide a single home for personal mpv Lua scripts so they share release tooling, lint rules, and documentation.
+- Keep each script self-documenting through richly annotated headers while this file explains meta-level conventions.
+
+## 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.
+- 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`).
+
+## Tooling
+- **Linting**: `luacheck scripts` (Lua 5.2 std, mp/mpv globals allowed, long format warnings suppressed via config).
+- **Formatting**: `stylua scripts` (2-space indent, 100-column width, Unix newlines, double quotes preferred).
+- **mpv runtime**: target mpv 0.36+ with the bundled Lua 5.2 interpreter; scripts should avoid third-party Lua modules unless vendored.
+- **Automation**: use `just` targets for common chores—`just fmt` formats, `just fmt-check` verifies formatting, `just lint` runs luacheck, and `just check` chains the formatting check plus lint.
+
+## Working With The Repo
+1. Add new scripts under `scripts/` and document behavior in the top comment block.
+2. Run `stylua` followed by `luacheck` before committing.
+3. Update this file when repo-level layout or tooling changes so future contributors understand the structure.

justfile

@@ -0,0 +1,10 @@
+lint:
+	luacheck scripts
+
+fmt:
+	stylua scripts
+
+fmt-check:
+	stylua --check scripts
+
+check: fmt-check lint

stylua.toml

@@ -0,0 +1,6 @@
+column_width = 100
+indent_type = "Spaces"
+indent_width = 2
+line_endings = "Unix"
+quote_style = "AutoPreferDouble"
+call_parentheses = "Always"