chore: add repo tooling

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.