feat: Homebrew-compatible releases + PATH-based skills

.github/workflows/auto-release.yml

@@ -90,6 +90,9 @@ jobs:
           - target: linux-x64
             os: ubuntu-latest
             artifact: upkeep-linux-x64
+          - target: linux-arm64
+            os: ubuntu-latest
+            artifact: upkeep-linux-arm64
           - target: darwin-arm64
             os: macos-latest
             artifact: upkeep-darwin-arm64
@@ -141,17 +144,36 @@ jobs:
         with:
           path: artifacts
 
-      - name: Prepare release files
+      - name: Package release archives
+        env:
+          VERSION: ${{ needs.version.outputs.version }}
         run: |
           mkdir -p release
-          cp artifacts/upkeep-linux-x64/upkeep-linux-x64 release/
-          cp artifacts/upkeep-darwin-arm64/upkeep-darwin-arm64 release/
-          cp artifacts/upkeep-darwin-x64/upkeep-darwin-x64 release/
-          cp artifacts/upkeep-windows-x64.exe/upkeep-windows-x64.exe release/
-          chmod +x release/upkeep-linux-x64
-          chmod +x release/upkeep-darwin-arm64
-          chmod +x release/upkeep-darwin-x64
+
+          # Tar+gzip each Unix binary as `upkeep` inside the archive, named
+          # upkeep_<version>_<os>_<arch>.tar.gz with Homebrew-style arch tokens.
+          archive() {
+            src="$1"; os="$2"; arch="$3"
+            cp "$src" upkeep
+            chmod +x upkeep
+            tar -czf "release/upkeep_${VERSION}_${os}_${arch}.tar.gz" upkeep
+            rm upkeep
+          }
+          archive artifacts/upkeep-linux-x64/upkeep-linux-x64       linux  amd64
+          archive artifacts/upkeep-linux-arm64/upkeep-linux-arm64   linux  arm64
+          archive artifacts/upkeep-darwin-x64/upkeep-darwin-x64     darwin amd64
+          archive artifacts/upkeep-darwin-arm64/upkeep-darwin-arm64 darwin arm64
+
+          # Windows ships as a raw .exe — Homebrew does not consume it.
+          cp artifacts/upkeep-windows-x64.exe/upkeep-windows-x64.exe \
+            "release/upkeep_${VERSION}_windows_amd64.exe"
+
+          # checksums.txt lists the sha256 of each tarball; the Homebrew tap
+          # downloads this to render per-platform url + sha256.
+          ( cd release && sha256sum upkeep_"${VERSION}"_*.tar.gz > checksums.txt )
+
           ls -la release/
+          cat release/checksums.txt
 
       - name: Generate changelog
         uses: orhun/git-cliff-action@v4
@@ -167,10 +189,9 @@ jobs:
         with:
           tag_name: ${{ needs.version.outputs.tag }}
           files: |
-            release/upkeep-linux-x64
-            release/upkeep-darwin-arm64
-            release/upkeep-darwin-x64
-            release/upkeep-windows-x64.exe
+            release/*.tar.gz
+            release/*.exe
+            release/checksums.txt
           body: ${{ steps.changelog.outputs.content }}
           draft: false
           prerelease: false

.gitignore

@@ -1,5 +1,7 @@
 .claude/
-docs/
+
+# Private/scratch working dir (drafts, specs, outreach — not for publishing)
+_/
 
 # Dependencies
 node_modules/

package.json

@@ -10,8 +10,9 @@
   "scripts": {
     "dev": "bun run src/cli/index.ts",
     "build": "bun build ./src/cli/index.ts --compile --outfile dist/upkeep",
-    "build:all": "bun run build:linux-x64 && bun run build:darwin-arm64 && bun run build:darwin-x64 && bun run build:windows-x64",
+    "build:all": "bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:darwin-arm64 && bun run build:darwin-x64 && bun run build:windows-x64",
     "build:linux-x64": "bun build ./src/cli/index.ts --compile --target=bun-linux-x64 --outfile dist/upkeep-linux-x64",
+    "build:linux-arm64": "bun build ./src/cli/index.ts --compile --target=bun-linux-arm64 --outfile dist/upkeep-linux-arm64",
     "build:darwin-arm64": "bun build ./src/cli/index.ts --compile --target=bun-darwin-arm64 --outfile dist/upkeep-darwin-arm64",
     "build:darwin-x64": "bun build ./src/cli/index.ts --compile --target=bun-darwin-x64 --outfile dist/upkeep-darwin-x64",
     "build:windows-x64": "bun build ./src/cli/index.ts --compile --target=bun-windows-x64 --outfile dist/upkeep-windows-x64.exe",

skills/upkeep-audit/SKILL.md

@@ -46,14 +46,25 @@ This skill helps you:
 
 ## Prerequisites
 
-- `./bin/upkeep` binary must be available in this skill's directory
+- The `upkeep` binary must be installed and available on your `PATH`. Install it with:
+  ```bash
+  brew install llbbl/tap/upkeep
+  ```
+  (or download a binary from the [GitHub releases](https://github.com/llbbl/upkeep/releases)).
+- Before running any `upkeep` command, verify it is on `PATH` and stop with a clear message if not:
+  ```bash
+  command -v upkeep >/dev/null 2>&1 || {
+    echo "upkeep not found on PATH — install it with: brew install llbbl/tap/upkeep" >&2
+    exit 1
+  }
+  ```
 
 ## Workflow
 
 ### Step 1: Run Security Audit
 
 ```bash
-./bin/upkeep audit --json
+upkeep audit --json
 ```
 
 This returns vulnerabilities with:
@@ -82,7 +93,7 @@ For each vulnerability, explain:
 For each fixable vulnerability:
 
 ```bash
-./bin/upkeep risk <package> --from <current> --to <fix-version> --json
+upkeep risk <package> --from <current> --to <fix-version> --json
 ```
 
 This helps understand:
@@ -102,11 +113,11 @@ This helps understand:
 **For transitive dependencies:**
 The fix often requires updating a parent dependency. Check which direct dependency pulls in the vulnerable package and update that instead.
 
-Use `./bin/upkeep imports <parent-package>` to understand the impact.
+Use `upkeep imports <parent-package>` to understand the impact.
 
 ### Step 5: Verify Fixes
 
-1. Re-run audit: `./bin/upkeep audit --json`
+1. Re-run audit: `upkeep audit --json`
 2. Run tests: `<pm> test`
 3. Check for regressions
 
@@ -122,8 +133,8 @@ Some vulnerabilities may not have fixes yet. Options:
 
 User: "Check my project for security issues"
 
-1. Run `./bin/upkeep detect --json` to understand the project
-2. Run `./bin/upkeep audit --json` to scan for vulnerabilities
+1. Run `upkeep detect --json` to understand the project
+2. Run `upkeep audit --json` to scan for vulnerabilities
 3. Present findings grouped by severity
 4. For each fixable vulnerability:
    - Explain the issue
@@ -146,11 +157,11 @@ User: "Check my project for security issues"
 
 | Command | Purpose |
 |---------|---------|
-| `./bin/upkeep audit` | Run security audit |
-| `./bin/upkeep detect` | Detect package manager |
-| `./bin/upkeep risk <pkg>` | Assess upgrade risk |
-| `./bin/upkeep imports <pkg>` | Find package usage |
-| `./bin/upkeep deps` | List all outdated packages |
+| `upkeep audit` | Run security audit |
+| `upkeep detect` | Detect package manager |
+| `upkeep risk <pkg>` | Assess upgrade risk |
+| `upkeep imports <pkg>` | Find package usage |
+| `upkeep deps` | List all outdated packages |
 
 ## Handling Common Scenarios
 
@@ -169,7 +180,7 @@ Lower priority since it doesn't affect production. Still fix if:
 
 ### Breaking Change Required for Fix
 
-1. Assess impact with `./bin/upkeep risk`
+1. Assess impact with `upkeep risk`
 2. Check migration guides
 3. Consider if the security risk outweighs the migration effort
 4. For critical vulns, usually worth the effort

skills/upkeep-deps/SKILL.md

@@ -45,15 +45,26 @@ This skill helps you upgrade dependencies safely by:
 
 ## Prerequisites
 
-- `./bin/upkeep` binary must be available in this skill's directory
+- The `upkeep` binary must be installed and available on your `PATH`. Install it with:
+  ```bash
+  brew install llbbl/tap/upkeep
+  ```
+  (or download a binary from the [GitHub releases](https://github.com/llbbl/upkeep/releases)).
+- Before running any `upkeep` command, verify it is on `PATH` and stop with a clear message if not:
+  ```bash
+  command -v upkeep >/dev/null 2>&1 || {
+    echo "upkeep not found on PATH — install it with: brew install llbbl/tap/upkeep" >&2
+    exit 1
+  }
+  ```
 - `gh` CLI for Dependabot PR integration (optional but recommended)
 
 ## Workflow
 
 ### Step 1: Detect Project Configuration
 
 ```bash
-./bin/upkeep detect --json
+upkeep detect --json
 ```
 
 This tells you:
@@ -64,15 +75,15 @@ This tells you:
 ### Step 2: Check for Dependabot PRs (if gh CLI available)
 
 ```bash
-./bin/upkeep dependabot --json
+upkeep dependabot --json
 ```
 
 Dependabot PRs are pre-tested and often the safest to merge first.
 
 ### Step 3: Get Outdated Packages
 
 ```bash
-./bin/upkeep deps --json
+upkeep deps --json
 ```
 
 This returns all outdated packages categorized by update type (major/minor/patch).
@@ -81,7 +92,7 @@ This returns all outdated packages categorized by update type (major/minor/patch
 
 Present upgrades to the user in this priority order:
 1. **Dependabot PRs** - Already have PRs ready, checks may be passing
-2. **Security fixes** - Check `./bin/upkeep audit --json` for vulnerabilities
+2. **Security fixes** - Check `upkeep audit --json` for vulnerabilities
 3. **Patch updates** - Lowest risk, bug fixes only
 4. **Minor updates** - New features, should be backward compatible
 5. **Major updates** - Breaking changes, highest risk
@@ -91,7 +102,7 @@ Present upgrades to the user in this priority order:
 Before upgrading, assess the risk:
 
 ```bash
-./bin/upkeep risk <package> --json
+upkeep risk <package> --json
 ```
 
 This analyzes:
@@ -136,9 +147,9 @@ For major upgrades, use explicit version:
 
 User: "Update my dependencies"
 
-1. Run `./bin/upkeep detect --json` to understand the project
-2. Run `./bin/upkeep deps --json` to see what's outdated
-3. Run `./bin/upkeep audit --json` to check for security issues
+1. Run `upkeep detect --json` to understand the project
+2. Run `upkeep deps --json` to see what's outdated
+3. Run `upkeep audit --json` to check for security issues
 4. Present a prioritized list to the user
 5. For approved upgrades, run risk assessment and execute
 6. Test after each upgrade
@@ -161,9 +172,9 @@ Only do this if:
 
 | Command | Purpose |
 |---------|---------|
-| `./bin/upkeep detect` | Detect project configuration |
-| `./bin/upkeep deps` | List outdated packages |
-| `./bin/upkeep audit` | Security vulnerability scan |
-| `./bin/upkeep imports <pkg>` | Find where package is used |
-| `./bin/upkeep risk <pkg>` | Assess upgrade risk |
-| `./bin/upkeep dependabot` | List Dependabot PRs |
+| `upkeep detect` | Detect project configuration |
+| `upkeep deps` | List outdated packages |
+| `upkeep audit` | Security vulnerability scan |
+| `upkeep imports <pkg>` | Find where package is used |
+| `upkeep risk <pkg>` | Assess upgrade risk |
+| `upkeep dependabot` | List Dependabot PRs |

skills/upkeep-quality/SKILL.md

@@ -45,7 +45,18 @@ This skill helps you:
 
 ## Prerequisites
 
-- `./bin/upkeep` binary must be available in this skill's directory
+- The `upkeep` binary must be installed and available on your `PATH`. Install it with:
+  ```bash
+  brew install llbbl/tap/upkeep
+  ```
+  (or download a binary from the [GitHub releases](https://github.com/llbbl/upkeep/releases)).
+- Before running any `upkeep` command, verify it is on `PATH` and stop with a clear message if not:
+  ```bash
+  command -v upkeep >/dev/null 2>&1 || {
+    echo "upkeep not found on PATH — install it with: brew install llbbl/tap/upkeep" >&2
+    exit 1
+  }
+  ```
 
 ## Quality Metrics
 
@@ -75,7 +86,7 @@ The quality score is calculated from 6 weighted metrics:
 ### Step 1: Generate Quality Report
 
 ```bash
-./bin/upkeep quality --json
+upkeep quality --json
 ```
 
 This returns:
@@ -125,7 +136,7 @@ Many issues can be fixed automatically:
 
 User: "How healthy is my project?"
 
-1. Run `./bin/upkeep quality --json`
+1. Run `upkeep quality --json`
 2. Present the grade and score prominently
 3. Show the breakdown chart
 4. Highlight areas needing attention
@@ -138,7 +149,7 @@ User: "How healthy is my project?"
 
 ```bash
 # Check outdated packages
-./bin/upkeep deps --json
+upkeep deps --json
 
 # Update all patch versions (usually safe)
 <pm> update
@@ -148,7 +159,7 @@ User: "How healthy is my project?"
 
 ```bash
 # Find vulnerabilities
-./bin/upkeep audit --json
+upkeep audit --json
 
 # Fix what's available
 <pm> audit fix  # npm
@@ -206,15 +217,15 @@ Consider adding `knip` or `ts-prune` for advanced detection.
 
 | Command | Purpose |
 |---------|---------|
-| `./bin/upkeep quality` | Generate quality report |
-| `./bin/upkeep detect` | Check project configuration |
-| `./bin/upkeep deps` | Dependency freshness details |
-| `./bin/upkeep audit` | Security details |
+| `upkeep quality` | Generate quality report |
+| `upkeep detect` | Check project configuration |
+| `upkeep deps` | Dependency freshness details |
+| `upkeep audit` | Security details |
 
 ## Tracking Progress
 
 After making improvements:
-1. Re-run `./bin/upkeep quality --json`
+1. Re-run `upkeep quality --json`
 2. Compare new score to previous
 3. Celebrate improvements!
 4. Plan next improvements if needed