docs: add workstation and macOS launchd guidance

.env.example

@@ -14,3 +14,6 @@ OPENAI_API_KEY=sk-your-openai-key
 # Default from config.yaml: /var/lib/foundrygate/foundrygate.db
 # Example for local non-root runs:
 # FOUNDRYGATE_DB_PATH=/home/you/.local/state/foundrygate/foundrygate.db
+
+# Optional explicit config override for wrappers, services, and packaged installs:
+# FOUNDRYGATE_CONFIG_FILE=/home/you/.config/foundrygate/config.yaml

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to FoundryGate should be documented here.
 
 The format is intentionally lightweight and human-readable. Group entries by release and focus on user-visible behavior, operational changes, and compatibility notes.
 
+## Unreleased
+
+### Added
+
+- Added a workstation operations guide for Linux, macOS, and Windows runtime layouts
+- Added a macOS `launchd` LaunchAgent example for local workstation installs
+- Added Windows PowerShell and Task Scheduler starter examples for local workstation installs
+- Added platform-aware runtime helper scripts so macOS can use the same `foundrygate-install` / `start` / `stop` / `status` flow style as Linux
+- Added a project-owned Homebrew formula plus `brew services` guidance for packaged macOS workstation installs
+- Added explicit `FOUNDRYGATE_CONFIG_FILE` config discovery and `foundrygate --config` / `--version` support so service wrappers and packaged installs can point to config outside the repo
+- Added a helper-level onboarding smoke test for explicit config/env/python wiring
+
+### Changed
+
+- Updated the README quickstart so Linux, macOS, Windows, and Homebrew paths are visible earlier
+- Replaced the weak PyPI workflow badge with clearer workstation and Homebrew badges
+
 ## v1.1.0 - 2026-03-16
 
 ### Added

Formula/foundrygate.rb

@@ -0,0 +1,86 @@
+class Foundrygate < Formula
+  desc "Local OpenAI-compatible AI gateway for OpenClaw and other AI-native clients"
+  homepage "https://github.com/typelicious/FoundryGate"
+  url "https://github.com/typelicious/FoundryGate/archive/refs/tags/v1.1.0.tar.gz"
+  sha256 "08ee8e530f6ed4d631b85028557947ffebc7edf53bbe51fd58d279a547ede033"
+  license "Apache-2.0"
+  head "https://github.com/typelicious/FoundryGate.git", branch: "main"
+
+  depends_on "python@3.13"
+
+  def install
+    python = Formula["python@3.13"].opt_bin/"python3.13"
+
+    system python, "-m", "venv", libexec
+    system libexec/"bin/pip", "install", "--upgrade", "pip", "setuptools", "wheel"
+    system libexec/"bin/pip", "install", buildpath
+
+    pkgshare.install buildpath.children
+
+    (bin/"foundrygate").write <<~SH
+      #!/bin/bash
+      set -euo pipefail
+      mkdir -p "#{etc}/foundrygate" "#{var}/lib/foundrygate"
+      export FOUNDRYGATE_CONFIG_FILE="${FOUNDRYGATE_CONFIG_FILE:-#{etc}/foundrygate/config.yaml}"
+      export FOUNDRYGATE_DB_PATH="${FOUNDRYGATE_DB_PATH:-#{var}/lib/foundrygate/foundrygate.db}"
+      cd "#{etc}/foundrygate"
+      exec "#{libexec}/bin/python" -m foundrygate.main "$@"
+    SH
+
+    (bin/"foundrygate-stats").write <<~SH
+      #!/bin/bash
+      set -euo pipefail
+      export FOUNDRYGATE_CONFIG_FILE="${FOUNDRYGATE_CONFIG_FILE:-#{etc}/foundrygate/config.yaml}"
+      export FOUNDRYGATE_DB_PATH="${FOUNDRYGATE_DB_PATH:-#{var}/lib/foundrygate/foundrygate.db}"
+      cd "#{etc}/foundrygate"
+      exec "#{libexec}/bin/foundrygate-stats" "$@"
+    SH
+
+    %w[
+      foundrygate-doctor
+      foundrygate-health
+      foundrygate-onboarding-report
+      foundrygate-onboarding-validate
+      foundrygate-update-check
+    ].each do |helper|
+      (bin/helper).write <<~SH
+        #!/bin/bash
+        set -euo pipefail
+        mkdir -p "#{etc}/foundrygate" "#{var}/lib/foundrygate"
+        export FOUNDRYGATE_CONFIG_FILE="${FOUNDRYGATE_CONFIG_FILE:-#{etc}/foundrygate/config.yaml}"
+        export FOUNDRYGATE_ENV_FILE="${FOUNDRYGATE_ENV_FILE:-#{etc}/foundrygate/foundrygate.env}"
+        export FOUNDRYGATE_DB_PATH="${FOUNDRYGATE_DB_PATH:-#{var}/lib/foundrygate/foundrygate.db}"
+        export FOUNDRYGATE_PYTHON="#{libexec}/bin/python"
+        exec "#{pkgshare}/scripts/#{helper}" "$@"
+      SH
+    end
+  end
+
+  def post_install
+    (etc/"foundrygate").mkpath
+    (var/"lib/foundrygate").mkpath
+    (var/"log/foundrygate").mkpath
+
+    config_path = etc/"foundrygate/config.yaml"
+    env_path = etc/"foundrygate/foundrygate.env"
+
+    config_path.write((pkgshare/"config.yaml").read) unless config_path.exist?
+    env_path.write((pkgshare/".env.example").read) unless env_path.exist?
+  end
+
+  service do
+    run [opt_bin/"foundrygate"]
+    working_dir etc/"foundrygate"
+    environment_variables(
+      FOUNDRYGATE_CONFIG_FILE: etc/"foundrygate/config.yaml",
+      FOUNDRYGATE_DB_PATH: var/"lib/foundrygate/foundrygate.db",
+    )
+    keep_alive true
+    log_path var/"log/foundrygate/output.log"
+    error_log_path var/"log/foundrygate/error.log"
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{libexec}/bin/python -c 'import foundrygate; print(foundrygate.__version__)'")
+  end
+end

README.md

@@ -7,14 +7,17 @@
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![OpenAI-compatible](https://img.shields.io/badge/OpenAI-compatible-0ea5e9.svg)](./docs/API.md)
 [![OpenClaw-friendly](https://img.shields.io/badge/OpenClaw-friendly-111827.svg)](https://openclaw.ai/)
+[![Workstations](https://img.shields.io/badge/workstations-linux%20%7C%20macOS%20%7C%20windows-0f766e.svg)](./docs/WORKSTATIONS.md)
+[![Homebrew](https://img.shields.io/badge/homebrew-formula-fbbf24?logo=homebrew&logoColor=black)](./Formula/foundrygate.rb)
 [![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)](./Dockerfile)
-[![PyPI](https://img.shields.io/badge/pypi-workflow%20ready-3775A9?logo=pypi&logoColor=white)](./RELEASES.md)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](./pyproject.toml)
 
 Local OpenAI-compatible AI gateway for 🦞 [OpenClaw](https://openclaw.ai/) and other AI-native clients.
 
 FoundryGate gives OpenClaw, n8n, CLI tools, and custom apps one local endpoint and routes each request to the best configured provider or local worker. It keeps routing, fallback, onboarding, and operator visibility under your control instead of scattering provider logic across every client.
 
+Runs locally on Linux, macOS, and Windows, with first-class workstation guidance for `systemd`, `launchd`, Task Scheduler, and Homebrew-driven macOS installs.
+
 ## Quick Navigation
 
 - [Quickstart](#quickstart)
@@ -39,6 +42,12 @@ FoundryGate gives OpenClaw, n8n, CLI tools, and custom apps one local endpoint a
 
 The fastest local path is the helper-driven bootstrap.
 
+Platform quick starts:
+
+- Linux or generic source checkout: use the helper/bootstrap flow below, then `systemd` if you want a long-running service.
+- macOS workstation: use the helper flow below or jump to [Homebrew](./docs/WORKSTATIONS.md#homebrew-on-macos) for `brew services`.
+- Windows workstation: use the source checkout flow below, then the PowerShell and Task Scheduler examples in [docs/WORKSTATIONS.md](./docs/WORKSTATIONS.md).
+
 ```bash
 git clone https://github.com/typelicious/FoundryGate.git foundrygate
 cd foundrygate
@@ -68,6 +77,14 @@ Then use the onboarding helpers to move from “the server starts” to “real
 
 If you prefer a packaged or service-driven install, jump to [Deployment](#deployment) or the fuller [Operations guide](./docs/OPERATIONS.md).
 
+Minimal Homebrew flow on macOS:
+
+```bash
+brew tap typelicious/foundrygate https://github.com/typelicious/FoundryGate
+brew install typelicious/foundrygate/foundrygate
+brew services start typelicious/foundrygate/foundrygate
+```
+
 ## How It Works
 
 ```text
@@ -151,6 +168,8 @@ FoundryGate can stay small in development and still scale into a more repeatable
 
 - Local Python run: quickest path for development and testing.
 - `systemd` on Linux: recommended for long-running generic host installs.
+- Workstation runtimes: macOS `launchd`, Linux `systemd`, and Windows task-scheduler style installs are documented separately.
+- Homebrew path: a project-owned tap formula now lives under [`Formula/foundrygate.rb`](./Formula/foundrygate.rb) for macOS-oriented installs and `brew services`.
 - Docker and GHCR path: tagged releases build container artifacts through the release workflow.
 - Python package path: release workflows build `sdist` and `wheel`.
 - Separate npm CLI package: `packages/foundrygate-cli` gives CLI-facing environments a small Node entry point without changing the Python service runtime.
@@ -159,6 +178,7 @@ Start here for the deeper deployment details:
 
 - [Configuration reference](./docs/CONFIGURATION.md)
 - [Operations guide](./docs/OPERATIONS.md)
+- [Workstations guide](./docs/WORKSTATIONS.md)
 - [Publishing and release flow](./docs/PUBLISHING.md)
 
 ## More Resources
@@ -168,9 +188,12 @@ Start here for the deeper deployment details:
 - [API reference](./docs/API.md)
 - [Configuration reference](./docs/CONFIGURATION.md)
 - [Operations guide](./docs/OPERATIONS.md)
+- [Workstations guide](./docs/WORKSTATIONS.md)
+- [Homebrew formula](./Formula/foundrygate.rb)
 - [Integrations](./docs/INTEGRATIONS.md)
 - [Onboarding](./docs/ONBOARDING.md)
 - [Examples](./docs/examples)
+- [macOS LaunchAgent example](./docs/examples/com.typelicious.foundrygate.plist)
 - [OpenClaw integration starter](./openclaw-integration.jsonc)
 - [Full OpenClaw example](./docs/examples/openclaw-foundrygate-full.jsonc)
 - [Multi-provider stack example](./docs/examples/foundrygate-multi-provider-stack.yaml)

RELEASES.md

@@ -16,6 +16,7 @@ This repo does not require a heavy release process. Use lightweight tags plus Gi
 8. Confirm that README plus the relevant docs pages still match the shipped runtime behavior.
 9. If packaging or Docker changed shortly before the release, run the publish dry run first.
 10. For hardening-heavy releases, keep the API functional tests green alongside unit and config coverage.
+11. If the Homebrew formula changed, bump [`Formula/foundrygate.rb`](./Formula/foundrygate.rb) to the new release tag and update its `sha256`.
 
 ## Example
 
@@ -73,6 +74,8 @@ The repo also includes [publish-dry-run](./.github/workflows/publish-dry-run.yml
 
 The npm package stays separate from the Python gateway core. It is meant for CLI-facing integrations, not for rewriting the service runtime.
 
+`v1.2.0` also starts the project-owned Homebrew path through [`Formula/foundrygate.rb`](./Formula/foundrygate.rb), intended for a dedicated tap or direct tap-by-URL workflow on macOS.
+
 ## Scheduled Deployment Examples
 
 FoundryGate now includes a conservative helper-driven update path for controlled environments. The recommended examples live in:

docs/FOUNDRYGATE-ROADMAP.md

@@ -19,7 +19,25 @@ The foundation that used to be the near-term buildout is largely in place:
 
 This roadmap now shifts from "rename and foundation" to "deepen the gateway plane without bloating it".
 
-`v1.0.0` is now shipped. The next block should stay disciplined: deepen AI-native client coverage, improve client-facing observability, and refine routing policy without turning FoundryGate into a sprawling platform.
+`v1.1.0` is now shipped. The next block should stay disciplined: improve workstation operations, keep adoption friction low across macOS and Windows, and extend runtime packaging guidance without turning FoundryGate into a sprawling platform.
+
+## `v1.2.0`: workstation operations baseline
+
+Primary goals:
+
+- add a dedicated workstation operations guide
+- document macOS `launchd` as a first-class local-runtime path
+- document Windows Task Scheduler / PowerShell as the baseline Windows path
+- keep development checkouts and runtime installs clearly separated
+- add a project-owned Homebrew packaging path for macOS workstations
+
+Recommended minimal slices:
+
+1. workstation baseline docs and path layout
+2. macOS `launchd` example and instructions
+3. Windows startup examples and documentation
+4. optional lightweight install helpers only if the docs prove insufficient
+5. Homebrew formula and `brew services` guidance for the packaged macOS path
 
 ## Post-1.0 direction
 

docs/OPERATIONS.md

@@ -31,6 +31,32 @@ Recommended persistent state path:
 
 That path is wired through `FOUNDRYGATE_DB_PATH`.
 
+### Workstation Runtime Installs
+
+For workstation usage, keep the runtime install separate from the development checkout.
+
+Recommended baseline:
+
+- Linux: `systemd` or `systemd --user`
+- macOS: `launchd` via `~/Library/LaunchAgents`
+- Windows: Task Scheduler plus direct venv Python invocation
+
+See [WORKSTATIONS.md](./WORKSTATIONS.md) for the path layout and OS-specific runtime guidance.
+
+### Homebrew On macOS
+
+For macOS workstations, FoundryGate now also ships a project-owned formula under [`Formula/foundrygate.rb`](../Formula/foundrygate.rb).
+
+Typical flow:
+
+```bash
+brew tap typelicious/foundrygate https://github.com/typelicious/FoundryGate
+brew install typelicious/foundrygate/foundrygate
+brew services start typelicious/foundrygate/foundrygate
+```
+
+That path keeps config under `$(brew --prefix)/etc/foundrygate`, state under `$(brew --prefix)/var/lib/foundrygate`, and logs under `$(brew --prefix)/var/log/foundrygate`.
+
 ### Docker / GHCR
 
 Tagged releases build container artifacts through the release workflow. For local validation you can build from the repo root:
@@ -56,6 +82,12 @@ That package is intentionally separate from the Python gateway runtime.
 
 FoundryGate ships optional wrappers around `systemd`, `journalctl`, `curl`, onboarding checks, and release-update flows.
 
+The runtime-control helpers now auto-detect Linux vs macOS:
+
+- on Linux they continue to use `systemd`
+- on macOS they manage the shipped `launchd` LaunchAgent
+- Windows remains documentation/example-driven for now
+
 | Script | What it does |
 | --- | --- |
 | `foundrygate-install` | install service + helper links |
@@ -110,6 +142,9 @@ The repo ships example schedules under [`docs/examples`](./examples):
 - `foundrygate-auto-update.service`
 - `foundrygate-auto-update.timer`
 - `foundrygate-auto-update.cron`
+- `com.typelicious.foundrygate.plist`
+- `foundrygate-start.ps1`
+- `foundrygate-task-scheduler.xml`
 
 Use them only after the manual update path is already validated.