docs(install): distinguish stable and HEAD Homebrew installs #24

Summary

The source README's default Homebrew instruction selects --HEAD, although the tap publishes a stable release URL. The command is valid, but it selects the moving development branch without explaining that channel choice.

Code evidence at 5d4987b:

• README.md:38 uses brew install --HEAD skill-cli/tap/skill-cli in the primary installation section.
• Documentation/Architecture/Package.md:80 assigns formulae and tap release instructions to the tap repository.
• The tap formula at 16aaf2d declares stable v0.2.1 and a separate master HEAD source; the tap README documents both channels.

Use Case

A user following the primary install guide should know whether they are choosing a tagged release or the current development branch.

Reproduction / current-state verification

Executed at 5d4987b. README/formula inspection was executed. Homebrew installation was not executed: this verifies channel selection without installing or upgrading a system package.

Run in Bash after cd "<checkout>" && swift build, replacing <checkout> with the absolute path of the checkout at this revision. Use a fresh reproduction directory. The commands isolate HOME, agent configuration, and XDG_*, and remove their fixture root on exit.

set -eu
checkout="<checkout>"
skill_bin="$checkout/.build/debug/skill"
repro_root="$checkout/.build/issue-repro-homebrew-doc"
mkdir -p "$repro_root/home" "$repro_root/tmp" "$repro_root/project"
trap 'rm -rf "$repro_root"' EXIT
isolated() {
  env -i PATH="$PATH" HOME="$repro_root/home" \
    CODEX_HOME="$repro_root/home/.codex" \
    CLAUDE_CONFIG_DIR="$repro_root/home/.claude" \
    XDG_CONFIG_HOME="$repro_root/home/.config" \
    XDG_STATE_HOME="$repro_root/home/.local/state" \
    XDG_CACHE_HOME="$repro_root/home/.cache" TMPDIR="$repro_root/tmp" \
    GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null \
    GIT_AUTHOR_NAME=Fixture [email protected] \
    GIT_COMMITTER_NAME=Fixture [email protected] \
    "$@"
}
skill() { isolated "$skill_bin" "$@"; }
cd "$repro_root/project"


cd "$checkout"
isolated rg -n 'brew install' README.md
isolated curl -fsSL https://raw.githubusercontent.com/skill-cli/homebrew-tap/16aaf2d3e978a76a16599af003e7e2fde1e38299/Formula/skill-cli.rb | \
  isolated grep -nE 'url |head |swift.*build'

Observed output (relevant lines; temporary paths shortened to <temp>):

38:brew install --HEAD skill-cli/tap/skill-cli
4:  url "https://github.com/skill-cli/cli/archive/refs/tags/v0.2.1.tar.gz"
7:  head "https://github.com/skill-cli/cli.git", branch: "master"
13:    system "swift", "build", "-c", "release", "--disable-sandbox", "--product", "skill"

Environment: Apple Swift 6.4, macOS 27.0.1 (26A434), arm64; CLI 0.2.1; validation date 2026-10-17.

Proposed Behavior

Decision: the normal install path uses the stable channel, brew install skill-cli/tap/skill-cli. --HEAD is documented separately as the development build of the master branch.

Completion checks:

• The default guide uses the stable command and matches the tap's supported commands.
• The --HEAD example is labeled as a development build and does not imply it installs the latest tag.
• Link to tap-owned release instructions rather than duplicating formula maintenance guidance.

Tradeoffs

HEAD may be an intentional recommendation while unreleased fixes are needed. If the maintainer retains it as the default, explain that choice and show the stable alternative. No broken-install claim is made.

Compatibility Notes

This changes guidance, not executable names or tap behavior. Preserve the documented skill and swift-skill entry points.

Related: PR #11 and PR #12 are source changes after the stable tag, making the channel distinction relevant; neither chooses the README's default channel. No duplicate found.