chore: protect main, Homebrew install path, and PR title checks (#11)

## Summary
- Document and rely on GitHub rulesets already applied to `main`
(PR-only, squash, required CI)
- Add conventional PR title check, CODEOWNERS, governance docs
- Make **Homebrew** the recommended macOS install + upgrade path (`brew
upgrade` / `brew autoupdate`)
- Release workflow bumps `Formula/microbridge.rb` via PR after each `v*`
tag

## Test plan
- [x] Rulesets created on repo (`Protect main`, `Protect release tags`)
- [ ] CI green on this PR (`rust`, `ui`, `conventional title`)
- [ ] Squash-merge into `main`


Made with [Cursor](https://cursor.com)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
  * Added automated pull request title validation.
  * Automated Homebrew formula updates after releases.
  * Added detailed governance and release process documentation.

* **Documentation**
* Reworked installation guidance for macOS, Linux, source builds, and
release binaries.
* Expanded contribution guidelines and updated README installation
instructions.

* **Release Improvements**
  * Added macOS release installation instructions.
  * Updated Homebrew metadata and installation caveats.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: DevVig

.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default owners for review routing (optional reviews; PRs still required on main).
+*       @DevVig
+
+/crates/                 @DevVig
+/apps/microbridge-ui/    @DevVig
+/adapters/               @DevVig
+/Formula/                @DevVig
+/.github/                @DevVig

.github/workflows/ci.yml

@@ -41,3 +41,6 @@ jobs:
           cache-dependency-path: apps/microbridge-ui/package-lock.json
       - run: npm ci
       - run: npm run build
+
+  # Keep required-check names stable for the main branch ruleset.
+  # Job names above are what GitHub shows as status contexts.

.github/workflows/pr-title.yml

@@ -0,0 +1,34 @@
+name: PR title
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint:
+    name: conventional title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            adapter
+            revert
+          requireScope: false
+          subjectPattern: .+
+          wip: true

.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   build:
@@ -18,7 +19,7 @@ jobs:
         include:
           - os: macos-latest
             target: aarch64-apple-darwin
-          - os: macos-13
+          - os: macos-latest
             target: x86_64-apple-darwin
           - os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
@@ -29,8 +30,7 @@ jobs:
           targets: ${{ matrix.target }}
       - uses: Swatinem/rust-cache@v2
       - name: Build
-        run: |
-          cargo build --release -p microbridged -p microbridgectl --target ${{ matrix.target }}
+        run: cargo build --release -p microbridged -p microbridgectl --target ${{ matrix.target }}
       - name: Package
         run: |
           STAGE=microbridge-${{ github.ref_name }}-${{ matrix.target }}
@@ -64,10 +64,46 @@ jobs:
           generate_release_notes: true
           files: release-assets/*
           body: |
-            ## Install
+            ## Install (macOS)
 
             ```sh
-            ./scripts/install-from-release.sh ${{ github.ref_name }}
+            brew tap DevVig/microbridge https://github.com/DevVig/microbridge
+            brew install microbridge
+            brew services start microbridge
             ```
 
-            Or from source: see [INSTALL.md](INSTALL.md).
+            Upgrade later: `brew update && brew upgrade microbridge`
+
+            Binary archive: `./scripts/install-from-release.sh ${{ github.ref_name }}`
+
+            Full guide: [INSTALL.md](INSTALL.md).
+
+  bump-formula:
+    name: bump Homebrew formula
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: main
+      - name: Bump Formula url + sha256
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          chmod +x scripts/bump-formula.sh
+          ./scripts/bump-formula.sh "${{ github.ref_name }}"
+      - name: Open PR
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore(brew): bump formula to ${{ github.ref_name }}"
+          title: "chore(brew): bump formula to ${{ github.ref_name }}"
+          body: |
+            Auto-bump `Formula/microbridge.rb` after release `${{ github.ref_name }}`.
+
+            After merge, users get the new version via:
+            ```sh
+            brew update && brew upgrade microbridge
+            ```
+          branch: chore/brew-${{ github.ref_name }}
+          delete-branch: true

CONTRIBUTING.md

@@ -53,12 +53,18 @@ Assets are attached to the GitHub Release; users can run
 
 ## Commits and PRs
 
-- Conventional commits (`feat:`, `fix:`, `docs:`, `adapter:` for adapter
-  work).
+`main` is protected — **no direct pushes**. Open a PR; squash-merge only.
+
+- PR titles must be Conventional Commits (`feat:`, `fix:`, `docs:`,
+  `adapter:`, …) — enforced by CI (`PR title` workflow).
+- Required checks: `rust (ubuntu-latest)`, `rust (macos-latest)`, `ui`.
+- Resolve review threads before merge.
 - One logical change per PR; small PRs merge fast here.
 - PRs must say how they were tested — "ran the reference adapter against the
   daemon and watched the frames" is a fine answer at this stage.
 
+See [docs/governance.md](docs/governance.md).
+
 ## Reporting security issues
 
 Privately, please — see [SECURITY.md](SECURITY.md).

Formula/microbridge.rb

@@ -1,11 +1,21 @@
-# Homebrew formula (build-from-source until a tap/bottle is published).
+# typed: false
+# frozen_string_literal: true
+
+# Homebrew formula for Microbridge (source build — fast enough for alpha).
 #
-#   brew install --build-from-source ./Formula/microbridge.rb
+#   brew tap DevVig/microbridge https://github.com/DevVig/microbridge
+#   brew install microbridge
 #   brew services start microbridge
 #
+# Upgrade (auto-update path):
+#   brew update && brew upgrade microbridge
+#   brew autoupdate start --upgrade --cleanup   # optional background updates
+#
 class Microbridge < Formula
   desc "Open-source control plane for the Codex Micro"
   homepage "https://github.com/DevVig/microbridge"
+  url "https://github.com/DevVig/microbridge/archive/refs/tags/v0.0.1.tar.gz"
+  sha256 "f171c275890add016045b0bbde54330f104b6d5db3a9d16c8d366cd5fcdde599"
   license any_of: ["MIT", "Apache-2.0"]
   head "https://github.com/DevVig/microbridge.git", branch: "main"
 
@@ -28,9 +38,10 @@ def install
 
   def caveats
     <<~EOS
-      Config and socket live in ~/.microbridge/
-      Check the bus with: microbridgectl status
-      Full install notes: #{doc}/INSTALL.md (or INSTALL.md in the repo)
+      Config and socket: ~/.microbridge/
+      Status:            microbridgectl status
+      Upgrade:           brew update && brew upgrade microbridge
+      Background updates: brew autoupdate start --upgrade --cleanup
     EOS
   end
 

INSTALL.md

@@ -1,111 +1,122 @@
 # Installing Microbridge
 
 Microbridge is a local daemon plus an optional companion UI. There is **no
-network** and **no cloud account** — install puts binaries on your machine and
-(on macOS) a per-user launchd agent.
+cloud account** — install puts binaries on your machine and runs a user-level
+service.
 
-## Requirements
-
-| Piece | Need |
-|---|---|
-| Daemon | Rust stable (`rustup`), macOS 13+ or Linux |
-| Companion UI (optional) | Node ≥ 20; full `.app` also needs Xcode CLT |
-| Hardware LEDs | Codex Micro over USB (HID packing still landing — mock works without hardware) |
+## Recommended on macOS: Homebrew (with updates)
 
-## Quick install (macOS, from source)
+This is the easy path. You do **not** need to clone the repo. Homebrew owns
+install, upgrades, and the launchd service.
 
 ```sh
-git clone https://github.com/DevVig/microbridge.git
-cd microbridge
-./scripts/install.sh
+brew tap DevVig/microbridge https://github.com/DevVig/microbridge
+brew install microbridge
+brew services start microbridge
+microbridgectl status
 ```
 
-This will:
-
-1. `cargo build --release` for `microbridged` and `microbridgectl`
-2. Install them to `~/.local/bin` (override with `MICROBRIDGE_BIN=…`)
-3. Ensure `~/.local/bin` is on your PATH (prints a hint if not)
-4. Install and start the launchd agent `ai.microbridge.daemon`
-5. Write config defaults under `~/.microbridge/`
-
-Verify:
+### Updates
 
 ```sh
-microbridgectl status
-# or:
-tail -f ~/.microbridge/daemon.log
+brew update && brew upgrade microbridge
+brew services restart microbridge
 ```
 
-### Optional companion UI
+Optional **background** upgrades (Homebrew’s autoupdate):
 
 ```sh
-./scripts/install.sh --with-ui
-# web preview during development:
-cd apps/microbridge-ui && npm install && npm run dev
+brew autoupdate start --upgrade --cleanup --immediate
+# later: brew autoupdate status / brew autoupdate stop
 ```
 
-`--with-ui` installs frontend deps and, when Tauri/Xcode tooling is available,
-attempts `npm run tauri build`. You can always run the Vite UI against a live
-daemon without bundling an `.app`.
+Private tap note: if the GitHub repo is private, authenticate once
+(`gh auth login` or a `HOMEBREW_GITHUB_API_TOKEN`) so `brew` can fetch the
+tarball.
 
-## Linux (from source)
+Uninstall:
 
 ```sh
-./scripts/install.sh --no-launchd
-# run in the foreground, or add your own systemd --user unit:
-microbridged
+brew services stop microbridge
+brew uninstall microbridge
+# optional: brew untap DevVig/microbridge
 ```
 
-A sample user unit is in [`scripts/microbridge.service`](scripts/microbridge.service).
+Governance / why this path: [docs/governance.md](docs/governance.md).
 
-## Homebrew (skeleton)
+---
+
+## Requirements
+
+| Piece | Need |
+|---|---|
+| Daemon (Homebrew) | Homebrew; Rust pulled in as a build dependency |
+| Daemon (from source) | Rust stable (`rustup`), macOS 13+ or Linux |
+| Companion UI (optional) | Node ≥ 20; full `.app` also needs Xcode CLT |
+| Hardware LEDs | Codex Micro over USB (HID packing still landing — mock works without hardware) |
+
+## From source (developers)
 
 ```sh
-brew install --build-from-source ./Formula/microbridge.rb
-brew services start microbridge   # when using the formula's service block
+git clone https://github.com/DevVig/microbridge.git
+cd microbridge
+./scripts/install.sh              # macOS: binaries + launchd
+# ./scripts/install.sh --with-ui
+# ./scripts/install-linux-systemd.sh
+microbridgectl status
 ```
 
-A published tap/bottle is not available yet — use `./scripts/install.sh` for
-day-to-day installs.
-
-## Install from a GitHub Release
+Uninstall: `./scripts/uninstall.sh` (add `--purge` to remove `~/.microbridge`).
 
-When a `v*` tag is pushed, CI attaches platform archives. Then:
+### Optional companion UI
 
 ```sh
-./scripts/install-from-release.sh v0.0.1
-# or latest:
-./scripts/install-from-release.sh
+./scripts/install.sh --with-ui
+# or during development:
+cd apps/microbridge-ui && npm install && npm run dev
 ```
 
-## Uninstall
+## Linux
 
 ```sh
-./scripts/uninstall.sh
+./scripts/install-linux-systemd.sh
+# or:
+./scripts/install.sh --no-launchd && microbridged
 ```
 
-Removes the launchd agent, binaries from `MICROBRIDGE_BIN` / `~/.local/bin`,
-and optionally (`--purge`) `~/.microbridge/` (config, socket, logs).
+Sample unit: [`scripts/microbridge.service`](scripts/microbridge.service).
+
+## Install from a GitHub Release (binaries)
+
+When a `v*` tag is published, CI attaches platform archives:
+
+```sh
+./scripts/install-from-release.sh          # latest
+./scripts/install-from-release.sh v0.0.1
+```
 
 ## Layout after install
 
 | Path | Purpose |
 |---|---|
-| `~/.local/bin/microbridged` | Daemon |
-| `~/.local/bin/microbridgectl` | CLI |
-| `~/Library/LaunchAgents/ai.microbridge.daemon.plist` | macOS autostart |
+| `$(brew --prefix)/bin/microbridged` | Daemon (Homebrew) |
+| `~/.local/bin/microbridged` | Daemon (source install script) |
 | `~/.microbridge/microbridged.sock` | Local NDJSON socket |
 | `~/.microbridge/config.toml` | Key source, lighting, appearance |
-| `~/.microbridge/daemon.log` | launchd stdout/stderr |
+| `~/.microbridge/daemon.log` | launchd / service logs |
 
 ## Troubleshooting
 
-**`microbridgectl: connect …`** — daemon not running. On macOS:
-`launchctl kickstart -k gui/$(id -u)/ai.microbridge.daemon`.
+**`microbridgectl: connect …`** — daemon not running.
+
+```sh
+brew services restart microbridge
+# or:
+launchctl kickstart -k "gui/$(id -u)/ai.microbridge.daemon"
+```
 
 **LEDs stay dark** — HID packing is still best-effort; ChatGPT desktop may
-also own the device. Pause that app or use Settings → Pause LEDs while testing
-the mock path (`microbridgectl status` still works).
+also own the device.
 
-**PATH** — add `export PATH="$HOME/.local/bin:$PATH"` to your shell rc if
-`microbridgectl` is not found.
+**Homebrew can’t fetch (private repo)** — `gh auth login`, or set
+`HOMEBREW_GITHUB_API_TOKEN` to a PAT with `repo` scope.