docs: document the contrib layout, tap submodule and developer workflow

AGENTS.md

@@ -31,8 +31,34 @@ synced `.venv/bin/python` explicitly.
 
 ```bash
 uv sync                                # resync the environment (do this first)
+git submodule update --init            # contrib/homebrew, the Homebrew tap
 uv run pytest                          # full test suite
 uvx ruff check .                       # lint (ruff is not a project dependency)
 uv run beefy-player --list             # station ids for the current catalogue
 uv run python tools/ansi_art.py ...    # regenerate a provider's header art
 ```
+
+`uvx ruff check .` is the enforced lint and must pass. `ruff format` is **not**
+enforced: the tree is not format-clean (54 files would change), so never run a
+repo-wide reformat as a side effect of an unrelated change.
+
+## Packaging
+
+`contrib/` holds the two distribution channels, and they work differently:
+
+- **`contrib/aur/`** — plain tracked files (`PKGBUILD`, `.SRCINFO`), edited
+  here. The package is not published in the AUR (sign-ups are closed), so
+  `makepkg -si` from a checkout is the only route. `_commit` pins the archive
+  the package builds from and must move with each release.
+- **`contrib/homebrew/`** — a **git submodule** of the tap at
+  `https://tildeforge.dev/beefcarver/homebrew`, not a copy. Formula changes
+  belong in the tap repository; commit them there and bump the gitlink here.
+  Never add loose files under that path. The formula still carries a
+  placeholder `sha256`, so it only installs with `--HEAD`.
+
+## Releases
+
+`.forgejo/workflows/release.yml` fires on a `v*` tag: it asserts that the tag,
+the `pyproject.toml` version and `beefy_player.__version__` all agree, then
+publishes release notes. It does **not** touch packaging, so bump
+`contrib/aur/PKGBUILD` (and its `.SRCINFO`) and the tap's formula by hand.