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.

README.md

@@ -102,22 +102,46 @@ too. From a checkout, `nix develop` gives you `uv`, `ruff` and the audio tools
 for the usual `uv sync` / `uv run pytest` workflow; `nix build` builds and
 tests the package.
 
+### Homebrew
+
+A tap lives at **[tildeforge.dev/beefcarver/homebrew](https://tildeforge.dev/beefcarver/homebrew)**.
+Homebrew's one-argument `brew tap` assumes GitHub, so point it at the tap URL
+and trust the formula explicitly:
+
+```bash
+brew tap beefcarver/homebrew https://tildeforge.dev/beefcarver/homebrew.git
+brew trust --formula beefcarver/homebrew/beefy-player
+brew install beefcarver/homebrew/beefy-player
+```
+
+`brew update` refreshes the tap and `brew upgrade` picks up new versions like
+any other formula. The formula builds from source, with `numpy`, `pillow`,
+`mpv` and `ffmpeg` pulled in as Homebrew dependencies.
+
+No release is tagged yet, so the formula still carries a placeholder checksum
+and cannot install from a tarball. Until the first `v*` tag is published, use
+`brew install --HEAD beefcarver/homebrew/beefy-player`.
+
+The tap is a git submodule at `contrib/homebrew`, so the formula and its
+maintenance notes live in the tap repository itself; after cloning this one,
+run `git submodule update --init` to check it out.
+
 ### Arch Linux
 
-The `aur/PKGBUILD` here is AUR-ready, but the package is not published in the
-AUR: the AUR has closed new sign-ups, so there is no account to push it to.
-Build and install it from a checkout instead:
+The `contrib/aur/PKGBUILD` here is AUR-ready, but the package is not published
+in the AUR: the AUR has closed new sign-ups, so there is no account to push it
+to. Build and install it from a checkout instead:
 
 ```bash
 git clone https://tildeforge.dev/beefcarver/beefy-player
-cd beefy-player/aur
+cd beefy-player/contrib/aur
 makepkg -si        # needs base-devel; builds, runs the test suite, installs
 ```
 
 Once the AUR accepts new accounts again, the package can be published and
 `paru -S beefy-player` / `yay -S beefy-player` will work; until then `makepkg`
-is the only route. The `aur/PKGBUILD` is tracked and kept in sync with every
-release either way.
+is the only route. The `contrib/aur/PKGBUILD` is tracked and kept in sync with
+every release either way.
 
 The Python side is pulled in automatically. For audio, the output-synced
 spectrum and image passthrough through tmux, install the optional tools too:
@@ -259,15 +283,32 @@ These stay in the usual XDG locations on every platform, macOS included;
 ## Development
 
 ```bash
-uv sync                 # create the environment
-uv run pytest           # test suite
-uvx ruff check .        # lint
+uv sync                         # create the environment
+git submodule update --init     # contrib/homebrew, the Homebrew tap
+uv run pytest                   # test suite
+uvx ruff check .                # lint
 ```
 
 Each catalogue is a self-contained provider module under
-`beefy_player/providers/`; `base.py` documents the interface. `tools/ansi_art.py`
-converts a PNG logo into half-block ANSI art. On NixOS, `nix develop` (or the
-older `shell.nix`) provides the same `uv sync` / `uv run` workflow.
+`beefy_player/providers/`; `base.py` documents the interface. Every catalogue's
+header is a wordmark from the shared half-block font, and the header paints it
+with the active palette gradient (`hero_gradient`, on by default) so all
+thirteen follow the terminal's colours. `tools/ansi_art.py` converts a PNG logo
+into half-block ANSI art that carries colours of its own; a provider using that
+art must set `hero_gradient = False`, because the header would otherwise
+repaint it with the gradient.
+
+`uvx ruff check .` is the enforced lint. The tree is not `ruff format`-clean (54
+files would change), so do not reformat it wholesale.
+
+Pushes run the test suite (`.forgejo/workflows/tests.yml`); a `v*` tag runs
+`release.yml`, which checks that the tag, `pyproject.toml` and
+`beefy_player.__version__` agree and then publishes the release notes. It does
+not touch packaging, so `contrib/aur/PKGBUILD` and the tap's formula are bumped
+by hand for each release.
+
+On NixOS, `nix develop` (or the older `shell.nix`) provides the same `uv sync` /
+`uv run` workflow.
 
 ## Licence