feat: add public CI, Homebrew, and benchmark assets

.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: GitHub CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  verify-go:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Verify formatting
+        run: test -z "$(gofmt -l .)"
+
+      - name: Verify module files
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod go.sum
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Run tests
+        run: go test ./...
+
+  verify-install-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Verify installer syntax
+        run: bash -n scripts/install.sh
+
+      - name: Build local release artifacts
+        run: |
+          TAG=v0.0.0-ci
+          bash scripts/release/build-artifacts.sh "${TAG}"
+          bash scripts/release/create-checksums.sh "${TAG}"
+
+      - name: Build local mirror layout
+        run: |
+          TAG=v0.0.0-ci
+          MIRROR_ROOT="${RUNNER_TEMP}/profitctl-mirror"
+          mkdir -p "${MIRROR_ROOT}/releases/${TAG}" "${MIRROR_ROOT}/current"
+          cp "dist/${TAG}/profitctl_${TAG}_"* "dist/${TAG}/SHA256SUMS" "${MIRROR_ROOT}/releases/${TAG}/"
+          printf '{"latest":"%s"}\n' "${TAG}" > "${MIRROR_ROOT}/current/index.json"
+          echo "PROFITCTL_TEST_MIRROR=file://${MIRROR_ROOT}" >> "${GITHUB_ENV}"
+
+      - name: Run installer smoke test
+        run: |
+          INSTALL_DIR="${RUNNER_TEMP}/profitctl-bin"
+          mkdir -p "${INSTALL_DIR}"
+          PROFITCTL_DOWNLOAD_BASE_URL="${PROFITCTL_TEST_MIRROR}" \
+          PROFITCTL_VERSION=v0.0.0-ci \
+          PROFITCTL_INSTALL_DIR="${INSTALL_DIR}" \
+          bash scripts/install.sh
+          "${INSTALL_DIR}/profitctl" --help >/dev/null
+          "${INSTALL_DIR}/profitctl" validate -f examples/mix_profit.yml >/dev/null

CHANGELOG.md

@@ -10,6 +10,9 @@ All notable changes to this project will be documented in this file.
 - OSS baseline docs and governance files.
 - Published-asset release smoke verification.
 - Design-partner issue routing and maintainer workflow guidance.
+- GitHub Actions PR/main verification workflow with stable `verify-go` and `verify-install-smoke` checks.
+- Homebrew formula and tap-publish script for the public release channel.
+- Committed benchmark comparison reports for open-core and hybrid pricing scenarios.
 
 ### Changed
 - Canonical module/repository identity aligned to `IntelIP/ProfitCtl`.
@@ -18,3 +21,4 @@ All notable changes to this project will be documented in this file.
 - Simulation benchmarks are now discoverable through `go test -bench`.
 - Public installer defaults now use GitHub Releases as the canonical source, with the Hostinger mirror available as an explicit override.
 - Open-core packaging docs now define who the product is for, what stays free, and what the first paid layer should cover.
+- Install docs now include Homebrew and the Quick Start includes concrete output snippets.

Formula/profitctl.rb

@@ -0,0 +1,35 @@
+class Profitctl < Formula
+  desc "CLI for profit-first unit economics simulations"
+  homepage "https://github.com/IntelIP/ProfitCtl"
+  version "0.1.2"
+  license "MIT"
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "https://github.com/IntelIP/ProfitCtl/releases/download/v#{version}/profitctl_v#{version}_darwin_arm64.tar.gz"
+      sha256 "7a16e98a82d96b8c1256deea599b10ee469bc5fa5e19b35a3ece803bc0b93a7d"
+    else
+      url "https://github.com/IntelIP/ProfitCtl/releases/download/v#{version}/profitctl_v#{version}_darwin_amd64.tar.gz"
+      sha256 "fc13529c0e44a7401d9c50ab75a56fbc63cbca0d4031bd69b737499ca264c951"
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm?
+      url "https://github.com/IntelIP/ProfitCtl/releases/download/v#{version}/profitctl_v#{version}_linux_arm64.tar.gz"
+      sha256 "4a744754afdbea618e07d74463d788e3e91c1fc67e506479263af8b09c7203af"
+    else
+      url "https://github.com/IntelIP/ProfitCtl/releases/download/v#{version}/profitctl_v#{version}_linux_amd64.tar.gz"
+      sha256 "425003e38aab4133a3cc37275a97ca31a008d9a011bfbbb9425bf43dbb33c712"
+    end
+  end
+
+  def install
+    bin.install "profitctl"
+    pkgshare.install "README.md" if File.exist?("README.md")
+  end
+
+  test do
+    assert_match "profit-first unit economics simulations", shell_output("#{bin}/profitctl --help")
+  end
+end

README.md

@@ -33,7 +33,14 @@ It helps teams model fixed + variable costs, simulate growth and stress scenario
 curl -fsSL https://raw.githubusercontent.com/IntelIP/ProfitCtl/main/scripts/install.sh | bash
 ```
 
-See [Install Guide](docs/INSTALL.md) for pinned versions, custom prefixes, and source-based installs.
+### Homebrew
+
+```bash
+brew tap IntelIP/profitctl
+brew install profitctl
+```
+
+See [Install Guide](docs/INSTALL.md) for pinned versions, Homebrew, custom prefixes, and source-based installs.
 
 ### Build from source
 

benchmark_scenarios/README.md

@@ -31,6 +31,12 @@ Use them with `profitctl compare` for pricing review:
 ./profitctl compare benchmark_scenarios/hybrid_operating_safe.yml benchmark_scenarios/hybrid_operating_breach.yml
 ```
 
+Committed shareable outputs now live under `benchmark_scenarios/reports/`:
+
+- `reports/open_core_tiered_vs_mix.md`
+- `reports/hybrid_steady_vs_pilot.md`
+- `reports/hybrid_safe_vs_breach.md`
+
 These scenarios are curated to answer three product questions:
 
 - should we ship open-core pricing as tiered bands or explicit plan mix?
@@ -53,6 +59,8 @@ Recommended starting pairs:
 - `hybrid_steady_contract.yml` vs `hybrid_pilot_contract.yml`
 - `hybrid_operating_safe.yml` vs `hybrid_operating_breach.yml`
 
+If you want an artifact to share instead of raw terminal output, start with the matching file in `benchmark_scenarios/reports/`.
+
 If you are turning one of these into a conversation, keep the frame simple:
 
 1. what are we comparing?

benchmark_scenarios/reports/hybrid_safe_vs_breach.md

@@ -0,0 +1,49 @@
+# Recurring Covenant Safety: Safe vs Breach
+
+Command:
+
+```bash
+profitctl compare benchmark_scenarios/hybrid_operating_safe.yml benchmark_scenarios/hybrid_operating_breach.yml --markdown
+```
+
+Question:
+
+What does a clearly covenant-safe hybrid contract look like against one that fails recurring operating health?
+
+Result:
+
+`hybrid_operating_breach` fails because operating margin drops well below the configured covenant threshold. This is the benchmark to show when the goal is risk detection, not just revenue comparison.
+
+Note:
+
+This command exits non-zero because the second scenario breaches its covenant. That is expected and useful in CI.
+
+Output:
+
+```markdown
+## profitctl Scenario Comparison
+
+Baseline: **hybrid_operating_safe**
+
+| Scenario | Mode | Revenue | Recurring Revenue | Payment Fees | Booked Margin | Operating Margin | Cost/User | Covenants |
+|----------|------|---------|-------------------|--------------|---------------|------------------|-----------|-----------|
+| hybrid_operating_safe | hybrid | $2000.00 | $2000.00 | $0.00 | 95.00% | 95.00% | $2.00 | PASS |
+| hybrid_operating_breach | hybrid | $250.00 | $250.00 | $0.00 | -100.00% | -100.00% | $10.00 | FAIL (1) |
+
+### Delta vs Baseline
+
+| Scenario | Revenue Delta | Booked Margin Delta | Operating Margin Delta | Cost/User Delta |
+|----------|---------------|---------------------|------------------------|-----------------|
+| hybrid_operating_breach | $-1750.00 | -195.00 pts | -195.00 pts | $+8.00 |
+
+### Failing Scenarios
+
+- **hybrid_operating_breach**: Operating margin must be >= 30%
+
+### Leaders
+
+- Highest revenue: **hybrid_operating_safe**
+- Highest operating margin: **hybrid_operating_safe**
+- Lowest cost/user: **hybrid_operating_safe**
+- Best covenant health: **hybrid_operating_safe**
+```

benchmark_scenarios/reports/hybrid_steady_vs_pilot.md

@@ -0,0 +1,41 @@
+# Hybrid Contracts: Steady-State vs Pilot
+
+Command:
+
+```bash
+profitctl compare benchmark_scenarios/hybrid_steady_contract.yml benchmark_scenarios/hybrid_pilot_contract.yml --markdown
+```
+
+Question:
+
+Does pilot revenue improve the contract, or does it only flatter booked economics while steady-state health gets worse?
+
+Result:
+
+The pilot contract increases total revenue, but it weakens operating margin and raises cost per user. This is the right benchmark to show when a team needs to separate one-time onboarding revenue from recurring business health.
+
+Output:
+
+```markdown
+## profitctl Scenario Comparison
+
+Baseline: **hybrid_steady_contract**
+
+| Scenario | Mode | Revenue | Recurring Revenue | Payment Fees | Booked Margin | Operating Margin | Cost/User | Covenants |
+|----------|------|---------|-------------------|--------------|---------------|------------------|-----------|-----------|
+| hybrid_steady_contract | hybrid | $2000.00 | $2000.00 | $0.00 | 95.00% | 95.00% | $2.00 | PASS |
+| hybrid_pilot_contract | hybrid | $6500.00 | $2000.00 | $200.50 | 95.38% | 91.50% | $3.40 | PASS |
+
+### Delta vs Baseline
+
+| Scenario | Revenue Delta | Booked Margin Delta | Operating Margin Delta | Cost/User Delta |
+|----------|---------------|---------------------|------------------------|-----------------|
+| hybrid_pilot_contract | $+4500.00 | +0.38 pts | -3.50 pts | $+1.40 |
+
+### Leaders
+
+- Highest revenue: **hybrid_pilot_contract**
+- Highest operating margin: **hybrid_steady_contract**
+- Lowest cost/user: **hybrid_steady_contract**
+- Best covenant health: **hybrid_pilot_contract**
+```

benchmark_scenarios/reports/open_core_tiered_vs_mix.md

@@ -0,0 +1,41 @@
+# Open-Core Pricing: Tiered vs Mix
+
+Command:
+
+```bash
+profitctl compare benchmark_scenarios/open_core_tiered.yml benchmark_scenarios/open_core_mix.yml --markdown
+```
+
+Question:
+
+Should the open-core packaging lead with cumulative tiered pricing or an explicit plan-mix model?
+
+Result:
+
+`open_core_tiered` wins on revenue, operating margin, and cost per user in the current benchmark assumptions. The `mix` configuration still passes covenants, but it gives up too much revenue without reducing cost enough to justify the trade.
+
+Output:
+
+```markdown
+## profitctl Scenario Comparison
+
+Baseline: **open_core_tiered**
+
+| Scenario | Mode | Revenue | Recurring Revenue | Payment Fees | Booked Margin | Operating Margin | Cost/User | Covenants |
+|----------|------|---------|-------------------|--------------|---------------|------------------|-----------|-----------|
+| open_core_tiered | tiered | $2425.00 | $2425.00 | $0.00 | 75.26% | 75.26% | $6.00 | PASS |
+| open_core_mix | mix | $880.00 | $880.00 | $35.66 | 27.77% | 27.77% | $6.36 | PASS |
+
+### Delta vs Baseline
+
+| Scenario | Revenue Delta | Booked Margin Delta | Operating Margin Delta | Cost/User Delta |
+|----------|---------------|---------------------|------------------------|-----------------|
+| open_core_mix | $-1545.00 | -47.49 pts | -47.49 pts | $+0.36 |
+
+### Leaders
+
+- Highest revenue: **open_core_tiered**
+- Highest operating margin: **open_core_tiered**
+- Lowest cost/user: **open_core_tiered**
+- Best covenant health: **open_core_tiered**
+```

docs/INSTALL.md

@@ -19,7 +19,20 @@ The script installs to `~/.local/bin` by default. If that directory is not on yo
 ## Pin a Version
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/IntelIP/ProfitCtl/main/scripts/install.sh | PROFITCTL_VERSION=v0.1.1 bash
+curl -fsSL https://raw.githubusercontent.com/IntelIP/ProfitCtl/main/scripts/install.sh | PROFITCTL_VERSION=v0.1.2 bash
+```
+
+## Homebrew
+
+```bash
+brew tap IntelIP/profitctl
+brew install profitctl
+```
+
+For explicit tap-qualified installs:
+
+```bash
+brew install IntelIP/profitctl/profitctl
 ```
 
 ## Custom Prefix
@@ -54,7 +67,7 @@ go install github.com/IntelIP/ProfitCtl@latest
 
 ```bash
 profitctl --help
-profitctl simulate --help
+profitctl validate -f examples/mix_profit.yml
 ```
 
 ## Exit Codes

docs/QUICK_START.md

@@ -9,6 +9,27 @@ profitctl simulate -f examples/hybrid_profit.yml
 profitctl simulate -f examples/hybrid_steady_profit.yml
 ```
 
+Example JSON excerpt from `examples/hybrid_steady_profit.yml`:
+
+```json
+{
+  "revenue": {
+    "mode": "hybrid",
+    "total": 2000,
+    "recurring_total": 2000,
+    "minimum_uplift": 500
+  },
+  "margin": {
+    "gross": 95,
+    "operating_gross": 95,
+    "cost_per_user": 2
+  },
+  "covenants": {
+    "passed": true
+  }
+}
+```
+
 ## 2. Validate config
 
 ```bash
@@ -44,6 +65,28 @@ profitctl compare examples/hybrid_steady_profit.yml examples/hybrid_profit.yml -
 The first config acts as the baseline. `compare` exits non-zero if any scenario breaches its covenants, which makes it usable in pricing reviews and CI gates.
 For hybrid and pilot-style contracts, the comparison output separates booked margin from operating margin so one-time setup revenue does not masquerade as steady-state unit economics.
 
+Example CLI excerpt:
+
+```text
+=== profitctl Scenario Comparison ===
+
+Baseline: open_core_tiered
+
+Scenario            Mode     Revenue    Recurring  Fees       Booked   Op Marg  CPU     Covenants
+------------------------------------------------------------------------------------------------
+open_core_tiered   tiered   $2425.00   $2425.00   $0.00      75.26    75.26    $6.00    PASS
+open_core_mix      mix      $880.00    $880.00    $35.66     27.77    27.77    $6.36    PASS
+
+Delta vs baseline:
+  open_core_mix: revenue -1545.00, booked -47.49 pts, operating -47.49 pts, cost/user +0.36
+```
+
+For committed shareable compare artifacts, see:
+
+- `benchmark_scenarios/reports/open_core_tiered_vs_mix.md`
+- `benchmark_scenarios/reports/hybrid_steady_vs_pilot.md`
+- `benchmark_scenarios/reports/hybrid_safe_vs_breach.md`
+
 ## 6. Normalize a calibration export
 
 ```bash