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

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