# 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. Use Conventional Commits for every git commit (e.g., `feat:`, `fix:`, `chore:`) so tooling can parse history cleanly.
4. Update this file when repo-level layout or tooling changes so future contributors understand the structure.