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.

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).

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.

Add new scripts under scripts/ and document behavior in the top comment block.
Run stylua followed by luacheck before committing.
Use Conventional Commits for every git commit (e.g., feat:, fix:, chore:) so tooling can parse history cleanly.
Update this file when repo-level layout or tooling changes so future contributors understand the structure.