From ad6fcc5732623dddfb55d17765ddbf0b743096b5 Mon Sep 17 00:00:00 2001
From: beefcarver <beefcarver@tilde.club>
Date: Thu, 5 Nov 2026 11:39:36 -0500
Subject: [PATCH] docs: add tap README covering install and trust

---
 README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3956f3b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# beefcarver/homebrew
+
+A [Homebrew](https://brew.sh) tap for tools by **beefcarver**.
+
+> [!IMPORTANT]
+> **This tap is not hosted on GitHub.** It lives at
+> [`tildeforge.dev/beefcarver/homebrew`](https://tildeforge.dev/beefcarver/homebrew),
+> so `brew tap` cannot guess its URL. You must pass the repository URL
+> explicitly, and you must trust the tap before Homebrew will load its formulae.
+
+## Formulae
+
+Formulae live under [`Formula/`](Formula/), sharded by the first letter of their
+name. See the directory for the currently available formulae.
+
+## Install
+
+Because this tap is self-hosted, tapping is an explicit two-step procedure: add
+it by URL, then grant trust.
+
+```sh
+# 1. Tap by full URL — the one-argument form assumes github.com and fails here
+brew tap beefcarver/homebrew https://tildeforge.dev/beefcarver/homebrew.git
+
+# 2. Trust it (see "Trust" below for a narrower option)
+brew trust beefcarver/homebrew
+
+# 3. Install a formula from the tap
+brew install <formula>
+```
+
+Building from `HEAD` instead of the latest release:
+
+```sh
+brew install --HEAD <formula>
+```
+
+### Trust
+
+A tap is a repository of Ruby: loading it runs code with your privileges, so
+non-official taps are untrusted by default since Homebrew 6.0.0. This tap is
+not an official Homebrew tap, and hosting it outside GitHub means there is no
+GitHub organisation vouching for it either — read the formula you intend to
+install before trusting anything.
+
+Prefer trusting only what you need:
+
+```sh
+brew trust --formula beefcarver/homebrew/<formula>
+brew install <formula>
+```
+
+Trusting the whole tap also trusts every formula ever added to it later:
+
+```sh
+brew trust beefcarver/homebrew
+```
+
+Inspect and revoke trust:
+
+```sh
+brew trust                            # list trusted taps and items
+brew untrust                          # list untrusted taps and items
+brew untrust beefcarver/homebrew      # revoke tap-wide trust
+```
+
+Do not disable the check with `HOMEBREW_NO_REQUIRE_TAP_TRUST`; it is deprecated
+and will be removed. See
+[Homebrew's Tap Trust documentation](https://docs.brew.sh/Tap-Trust).
+
+## Upgrading and removing
+
+```sh
+brew update
+brew upgrade <formula>
+
+brew uninstall <formula>
+brew untap beefcarver/homebrew
+```
+
+## Repository layout
+
+```
+Formula/
+└── <first-letter>/
+    └── <formula>.rb    # sharded by first letter, per Homebrew convention
+```
+
+## Working on a formula
+
+```sh
+brew install --build-from-source ./Formula/<first-letter>/<formula>.rb   # local build
+brew audit --strict --online <formula>                                   # lint
+brew style <formula>                                                     # rubocop
+brew test <formula>                                                      # run test block
+```
+
+If a formula builds a Python virtualenv, regenerate its resource blocks after
+changing the version or dependencies:
+
+```sh
+brew update-python-resources <formula>
+```
+
+### Adding a new formula
+
+1. Create `Formula/<first-letter>/<name>.rb`.
+2. Fill in `desc`, `homepage`, `url`, and a real `sha256`
+   (`brew fetch --build-from-source <url>` prints the checksum).
+3. `brew audit --new --strict <name>` to check it.
+4. Commit, push, and tell users about the trust requirement.
+
+## License
+
+Each formula is distributed under the license of the software it packages.