fix(docs): what cutting v0.1.0 turned up

[willkg]

Everything v0.1.0 turned up by actually being cut. The release process worked, and the documentation of it was wrong in four places — three of which only a real release could expose.

What the release proved

v0.1.0 shipped, and brew install markfluence works. The shipped binary reports markfluence 0.1.0 (1d0a2d0, 2026-09-20), so the ldflags stamp lands correctly on the real artifact — which was the last thing in #175 that could only be verified by doing it.

brew trust is required, and nothing said so

The install instructions were incomplete. Homebrew will not load a cask from a non-official tap until the tap is trusted, so brew tap followed by brew install fails on a clean machine. brew trust mozilla/markfluence goes between them.

This is the kind of thing no amount of reading the goreleaser config would have surfaced — it is a property of Homebrew's handling of third-party taps, not of what we generate.

The verify step downloaded into the repository root

Step 6 said mkdir tmp and then ran gh release download with no cd, so the archive, checksums.txt and the extracted binary all landed in the repo root, and the rm -rf tmp at the end removed an empty directory and left them behind. Now pushd tmp / popd, which also returns you to where you started — better than the cd "$(mktemp -d)" it replaced, which stranded you in /var/folders/….

/tmp/ is added to .gitignore, because the runbook now tells you to create a directory of untracked files — one of them a binary — inside the repository.

And gh release download is now inside the && chain. It was on its own line, so a failed download did not stop the verification: it went on to verify whatever was already in the directory. That is not hypothetical — it happened while testing this, where a stale archive from a previous attempt verified OK and printed a version that was right only by luck. On a version bump it would confirm the previous release. Same class of bug as the unchained sha256sum fixed in #177.

The step was then re-run end to end against the real v0.1.0 release, which is where the version stamp above comes from.

Release notes are not hard-wrapped

GitHub renders newlines in a release body as line breaks, so a paragraph wrapped at 80 columns renders ragged. Recorded in the runbook next to the gh release edit command, since that is where someone is standing when it matters.

CLAUDE.md records the release workflow

An omission from #177: the Build/distribution section enumerated the build tooling and said nothing about .github/workflows/release.yml, which CLAUDE.md's own rule requires. It now covers the four things that would otherwise have to be re-derived from the workflow file:

• the v*.*.* trigger, and why a bare v* breaks once Ship markfluence as a reusable GitHub Action #29's moving major tag exists
• make check against the tagged commit, since a tag can be pushed at any commit
• draft-then-publish, and that prerelease: auto is required rather than default — with why the gap was easy to miss, since the cask is correctly skipped for an RC by a different mechanism
• contents: write but deliberately not pull-requests: write, with the ruleset reason

Plus a pointer to docs/releasing.md as the runbook, and a note that naming archives.files is what makes the archive flat — which is why the Linux install instructions extract a single member rather than the whole thing.

Also

The two "no release has been cut yet" admonitions are gone from README.md and docs/releasing.md, since one has been. That was the last item on #175's closing checklist; the issue should be closeable once this lands.

Some of the runbook's prose is tightened and a few explanatory paragraphs become [!NOTE] blocks, which is presentational.