docs: add Colima and docker-buildx setup instructions for macOS (#474)

macOS users using Colima instead of Docker Desktop were hitting
missing buildx errors and had no documentation to guide them.
Add Colima as a supported Docker runtime, document buildx
installation, and ensure setup-local installs buildx automatically.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -28,6 +28,7 @@
 ### Supported Systems
 
 - **Linux x86_64** (fully supported)
+- **macOS** (local development supported via Docker Desktop or Colima)
 - **ARM64** (partial support for upstream Google OSS-Fuzz projects)
 
 ### Required System Packages
@@ -75,6 +76,14 @@ This script will install all dependencies, configure the environment, and guide
 
 **Note:** If you prefer manual setup, see the [Manual Setup Guide](guides/MANUAL_SETUP.md).
 
+1. Ensure Docker is running before deploying:
+
+```bash
+# Docker Desktop: start the application
+# Colima (macOS/Linux alternative):
+colima start --cpu 6 --memory 10 --disk 80
+```
+
 1. Start Buttercup locally
 
 ```bash

deployment/README.md

@@ -32,16 +32,17 @@ This section covers deploying the CRS locally using minikube on macOS or Linux.
 
 ### Local Prerequisites
 
-- **Docker Desktop** (macOS/Windows) or Docker Engine (Linux)
+- **Docker Desktop** (macOS/Windows), **Colima** (macOS/Linux), or Docker Engine (Linux)
+- **docker-buildx**: Required for building images (`brew install docker-buildx` on macOS)
 - **minikube**: `brew install minikube` (macOS) or see [minikube install docs](https://minikube.sigs.k8s.io/docs/start/)
 - **helm**: `brew install helm` (macOS)
 - **kubectl**: `brew install kubectl` (macOS)
 
-### Docker Desktop Resource Configuration
+### Docker Resource Configuration
 
-Docker Desktop has default resource limits that are typically too low for the full CRS deployment.
+The Docker runtime must have enough resources allocated for the full CRS deployment.
 
-**To configure Docker Desktop resources (macOS):**
+**Docker Desktop (macOS/Windows):**
 1. Open Docker Desktop > Settings > Resources
 2. Allocate at least:
    - CPUs: 4-6 (depending on your machine)
@@ -49,7 +50,24 @@ Docker Desktop has default resource limits that are typically too low for the fu
    - Disk: 80+ GB
 3. Click "Apply & Restart"
 
-**Important**: Minikube cannot use more resources than Docker Desktop allocates. If `env.template` specifies `MINIKUBE_CPU=6` and `MINIKUBE_MEMORY_GB=10`, but Docker Desktop only has 4 CPUs and 8GB RAM, minikube will fail to start or pods will remain Pending.
+**Colima (macOS/Linux):**
+```bash
+colima start --cpu 6 --memory 10 --disk 80
+```
+
+After starting Colima, ensure the buildx plugin is linked:
+```bash
+brew install docker-buildx
+```
+
+`docker-buildx` is a Docker plugin. For Docker to find the plugin, add "cliPluginsExtraDirs" to ~/.docker/config.json:
+```json
+"cliPluginsExtraDirs": [
+  "/opt/homebrew/lib/docker/cli-plugins"
+]
+```
+
+**Important**: Minikube cannot use more resources than the Docker runtime allocates. If `env.template` specifies `MINIKUBE_CPU=6` and `MINIKUBE_MEMORY_GB=10`, but Docker only has 4 CPUs and 8GB RAM, minikube will fail to start or pods will remain Pending.
 
 ### Quick Start
 

scripts/common.sh

@@ -807,6 +807,31 @@ check_brew() {
     fi
 }
 
+# Register Homebrew cli-plugins dir so Docker discovers plugins like
+# buildx. Prefers patching ~/.docker/config.json via jq; falls back
+# to a per-plugin symlink when jq is not installed.
+ensure_docker_cli_plugins_dir() {
+    local plugins_dir="/opt/homebrew/lib/docker/cli-plugins"
+    local config_file="$HOME/.docker/config.json"
+
+    if command_exists jq; then
+        mkdir -p "$(dirname "$config_file")"
+        if [ ! -f "$config_file" ]; then
+            echo '{}' > "$config_file"
+        fi
+        # Idempotent: appends only if the path isn't already listed
+        local tmp="${config_file}.tmp"
+        jq --arg d "$plugins_dir" \
+            '.cliPluginsExtraDirs = ((.cliPluginsExtraDirs // []) | if index($d) then . else . + [$d] end)' \
+            "$config_file" > "$tmp" && mv "$tmp" "$config_file"
+    else
+        print_warning "jq not found — falling back to symlink for docker-buildx"
+        mkdir -p ~/.docker/cli-plugins
+        ln -sfn "$(brew --prefix docker-buildx)/lib/docker/cli-plugins/docker-buildx" \
+            ~/.docker/cli-plugins/docker-buildx
+    fi
+}
+
 install_docker_mac() {
     if command_exists docker; then
         print_success "Docker is already installed"
@@ -814,6 +839,18 @@ install_docker_mac() {
         print_status "Installing Docker..."
         brew install --cask docker
     fi
+
+    # Ensure docker-buildx is available (bundled with Docker Desktop,
+    # but must be installed separately for Colima users)
+    if ! docker buildx version >/dev/null 2>&1; then
+        print_status "Installing docker-buildx plugin..."
+        brew install docker-buildx
+        # Register Homebrew cli-plugins dir so Docker discovers buildx
+        ensure_docker_cli_plugins_dir
+        print_success "docker-buildx installed"
+    else
+        print_success "docker-buildx is available"
+    fi
 }
 
 install_uv_mac() {