feat(phase-4): packaging — releases, npm, homebrew tap

[sonpiaz]

Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

Closes Phase 4 of the watch-cli foundation: tagged releases, an npm-published MCP server, and a Homebrew tap. Together these turn the v1 output schema promise into a concrete artifact contract — v1 means "the tarball at tag v1.x.y" — and replace the current "everyone installs from main HEAD" footgun.

Items shipped

Item	Where	Why
lib/version.sh — single VERSION source of truth	lib/version.sh (new)	Bumping a release was a two-place edit (bin/watch line 41 + lib/env.sh). One source kills the drift risk. CI guardrail check lives in docs/releases.md §"CI guardrail".
All 6 bin scripts source lib/version.sh	bin/{watch,dl-video,extract-frames,transcribe,audio-q,models}	Each --version flag now prints $WATCH_CLI_VERSION_STRING. bin/dl-video and bin/extract-frames gained the standard symlink-resolve preamble so they can source the lib.
lib/env.sh sources lib/version.sh	lib/env.sh	Old WATCH_CLI_VERSION="0.2.0" removed. User-Agent header now derives from the single constant.
Version bump 0.2.0 → 0.3.0	lib/version.sh, mcp-server/package.json	First release under the new workflow. mcp-server version stays in lockstep with watch-cli — both bumped to 0.3.0.
.github/workflows/release.yml	new file	Triggers on push: tags: ['v*']. Three jobs: release (verify-tag-on-main, verify-version, build tarball, generate notes, gh release create), publish-mcp (npm version sync + build + publish), bump-tap (open PR against sonpiaz/homebrew-tap with new version + sha256).
install.sh fetches release tarball	install.sh	Default = releases/latest/download/watch-cli.tar.gz. WATCH_CLI_VERSION env → pins. Falls back to git clone if no release exists (bootstrap window). SHA256-verifies against the published watch-cli.tar.gz.sha256.
README install section adds Homebrew	README.md	Brew tap option above the curl one-liner, with note that it requires v0.3.0 to ship first.
docs/releases.md documents secrets	docs/releases.md	Each required secret now lists the exact manual setup the user must do.
sonpiaz/homebrew-tap bootstrapped	external repo	Repo already existed (has Kapt + Yap casks). Added Formula/watch-cli.rb + README entry. Commit: sonpiaz/homebrew-tap@2e638fa. SHA256 is placeholder until v0.3.0 ships.

User action items (BLOCKS first release)

Before tagging v0.3.0, Son must do these three things manually — the workflow can't generate secrets on its own:

1. Generate NPM_TOKEN (Automation type) at https://www.npmjs.com/settings/sonpiaz/tokens, paste into watch-cli repo Settings → Secrets and variables → Actions. Without this, the publish-mcp job fails; GH Release + tarball + tap PR still succeed.
2. Generate HOMEBREW_TAP_PAT (fine-grained, scoped to sonpiaz/homebrew-tap only, perms: contents:write + pull-requests:write + metadata:read, 1-year expiry) at https://github.com/settings/personal-access-tokens. Paste into the same secrets page. Without this, the bump-tap job fails; GH Release + tarball + npm publish still succeed.
3. After CI is green on this PR and it merges to main:

   git checkout main && git pull --rebase
   git tag -a v0.3.0 -m "v0.3.0"
   git push origin v0.3.0

   This fires the release workflow. Once it completes, edit Formula/watch-cli.rb in the tap PR to use the real sha256 from the release asset (auto-bump fills it; reviewer only needs to verify + merge).

Test plan

• bash -n on all 6 bin scripts + install.sh — pass
• All 6 bins print watch-cli v0.3.0 on --version
• bash tests/test-output-schema.sh — all assertions pass
• release.yml parses as valid YAML (python3 -m yaml)
• Formula/watch-cli.rb committed + pushed to sonpiaz/homebrew-tap
• (post-merge) Tag v0.3.0; workflow creates GH Release + tarball
• (post-merge) curl -fsSL releases/latest/download/install.sh | bash on a clean container succeeds
• (post-merge) WATCH_CLI_VERSION=0.3.0 curl … pins correctly
• (post-merge) Tap PR auto-opens; merge it; brew install sonpiaz/tap/watch-cli on a clean Mac works end-to-end
• (post-merge) @sonpiaz/[email protected] resolvable on npm

Reviewer checklist

• VERSION = 0.3.0 is the only literal version string left in the tree (grep -r "0\.2\.0" . returns nothing meaningful)
• release.yml verify-version step would catch a tag/lib drift
• install.sh git-clone fallback is preserved for the bootstrap window
• bin/watch --help and bin/dl-video --help line ranges still capture the right comment block after the preamble insertion
• docs/releases.md "Required repo secrets" section spells out the manual setup
• Formula/watch-cli.rb desc line is exactly the 71-char locked variant from BRANDING.md (no hype words)