build: the release workflow, and per-platform install instructions

[willkg]

The code half of #175. .goreleaser.yaml has been fully configured since the start and never once invoked; this is the thing that invokes it, plus the install instructions and the policy statements that a first release makes true. Cutting v0.1.0 itself is still a manual step and is not in this PR.

No Go code changes. make check, goreleaser check and zizmor are all green.

.github/workflows/release.yml

Tag-triggered, make check against the tagged commit, then goreleaser, then publish. Four decisions in it are not guessable from the config:

Triggered on v*.*.*, not v*. The obvious glob also matches the moving major tag #29 needs, so every release would re-enter the workflow and the second run would fail on a tag goreleaser refuses as non-semver. Actions tag filters are globs rather than regex, so three components is the available way to say it.

make check runs against the tag. A tag can be pushed at any commit, so this is what makes "it passed CI" true of the thing actually being released rather than of a branch that resembles it.

The release is created as a draft and published last. This closes a hole the #176 review found: goreleaser creates the GitHub Release before uploading assets, and /releases/latest is the most recent published non-prerelease whether or not its assets are complete. So a run that died mid-upload would become the release latest resolves to — and latest is what the README sends Linux users to and what #29's action defaults to. Publishing last means a failure leaves a draft nobody downstream sees.

contents: write only, deliberately not pull-requests: write. goreleaser pushes the cask branch and stops; a human opens the PR. The reason is measured and lives in docs/releasing.md: a PR opened with this token would never trigger ci, and main's ruleset requires that check with nobody able to bypass it.

zizmor reports nothing on the file. Every action pinned by commit SHA, no input interpolated into a run: block, persist-credentials: false since goreleaser authenticates over the API rather than git, and the module cache disabled — a cache is writable from less-trusted contexts and this job builds the artifacts people install. cache: false has to be explicit, because setup-go caches by default and merely dropping cache: true left the finding standing.

(zizmor also reports artipacked against the pre-existing ci.yml. Left alone as out of scope.)

prerelease: auto, which is not the default

Worth calling out separately because it inverted the draft mechanism. release.prerelease defaults to false, so a v0.1.0-rc.1 tag — which docs/releasing.md blesses as the way to rehearse a release — produced a non-prerelease draft, which the publish step then published unconditionally. The release candidate would have become /releases/latest: exactly the outcome the draft was added to prevent, reached from the other direction.

Easy to miss because the visible half behaved correctly: the Homebrew cask really is skipped for an RC, since skip_upload: "auto" reads the parsed semver rather than this setting. So a rehearsal would have looked right while publishing a live release. It also falsified a sentence already in the runbook claiming goreleaser marks prereleases on its own.

Install instructions, per platform

The Install section offered "from source" and a Homebrew heading reading TBD. Now that the cask is real (#1) it can say what each platform should do, and the answers differ.

macOS is Homebrew, with the explicit-URL tap — the one non-obvious step, since this repo is its own tap and is not named homebrew-markfluence. That now appears where somebody installing will read it rather than only in a YAML comment.

Linux is a release archive. Homebrew is deliberately not offered there: it runs on Linux, but it distributes this binary as a cask, and Cask is a macOS feature. That also settles the "does the cask work on Linux" question that .goreleaser.yaml had recorded as unverified — by not asking it. No instruction depends on it now.

The Linux snippet was verified by running it against real goreleaser-built archives rather than by reading it, which caught three faults in a block whose whole purpose is to be pasted verbatim:

• tar -xzf extracted everything into the working directory, and the archive is flat — LICENSE, README.md, completions/, markfluence. Run in a home directory or a project checkout, which is exactly where someone installing a CLI is standing, it silently overwrote their own README.md and LICENSE. Tested with decoy files; it now extracts only the binary and they survive.
• The commands ran unchained, so a failing sha256sum --check printed FAILED and the install proceeded anyway — the verification was advisory against the one failure it exists to catch.
• install -m 0755 … ~/.local/bin/ fails outright when ~/.local/bin does not exist, which is the common case on a fresh machine.

Verified working: the checksum check (correctly ignoring the three archives not downloaded) and the single-member extraction. Not yet verified: install -D on Linux — it cannot be tested here, because macOS ships BSD install where -D means something unrelated. GNU coreutils install -D creates leading directories, which is what the instruction relies on.

docs/releasing.md and SECURITY.md

The runbook's admonition drops from IMPORTANT to a NOTE: release.yml exists now, so saying it does not is wrong, but nothing has run end to end and the first attempt should be expected to turn something up. The watch step describes the draft flow, and the failure section describes recovering a draft rather than retracting a published release — and now also deletes the goreleaser/cask-<tag> branch, which a failed run has already pushed, since re-tagging would otherwise stack a second cask on the stale one.

Its verify step also verified nothing: it said "download an archive and check the stamp" and then gave markfluence --version, which runs whatever is on $PATH — for a maintainer the make install build stamped dev. It passed no matter what shipped. It now downloads, checksums, extracts and runs ./markfluence --version.

SECURITY.md states the actual pre-1.0 policy rather than saying there has never been a release: latest release only, no backports, upgrade is the answer. The version table itself is still #95.

Known and deliberate

• A NOTE at the top of Install says no release exists yet, because the brew and archive instructions describe something there is nothing to fetch for until v0.1.0 ships. It comes out with the one in docs/releasing.md, as part of closing Establish the release process and cut v0.1.0 #175.
• go install produces an unstamped dev build, since it applies no ldflags. Documented rather than fixed: buildinfo.Version is read as a package var in three places and adding a debug.ReadBuildInfo().Main.Version fallback is a separate concern from release infrastructure. Worth its own issue.
• ~/.local/bin may not be on PATH in the session that created it — Debian/Ubuntu and Fedora both add it at login only if it already exists. Not currently mentioned in the README.