From 6f05bdaff5b2fc10827f6184627073de9a6fe600 Mon Sep 17 00:00:00 2001
From: norrietaylor <norrie@minimal.dev>
Date: Thu, 23 Apr 2026 14:57:11 -0700
Subject: [PATCH 1/3] feat: add local macOS launchd installer with scheduled
 pipelines
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Installs a supervised Distillery HTTP server as a LaunchAgent plus four
scheduled webhook agents (poll every 30 min, classify every 2 h, rescore
daily, maintenance weekly) and a weekly image-update agent. All ingestion
goes through the running server's /api/* surface — DuckDB is single-writer
and the server owns the lock, so sibling CLI processes can't write.

Secrets (JINA_API_KEY, DISTILLERY_WEBHOOK_SECRET) live in the macOS login
Keychain; the webhook secret is generated on first install. The installer
is idempotent and auto-detects OrbStack vs Docker Desktop. Uninstaller
preserves the DB and Keychain entries by default.

Adds a 'Local macOS (launchd)' page under Getting Started with setup,
verification, customization, and troubleshooting.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 docs/getting-started/local-macos.md           | 166 ++++++++++++
 mkdocs.yml                                    |   1 +
 scripts/local-macos/README.md                 |  48 ++++
 scripts/local-macos/install.sh                | 239 ++++++++++++++++++
 .../local-macos/templates/_webhook_common.sh  |  46 ++++
 scripts/local-macos/templates/classify.sh     |   8 +
 scripts/local-macos/templates/distillery.yaml |  40 +++
 .../launchd/local.distillery-classify.plist   |  28 ++
 .../local.distillery-maintenance.plist        |  39 +++
 .../launchd/local.distillery-poll.plist       |  28 ++
 .../launchd/local.distillery-rescore.plist    |  36 +++
 .../launchd/local.distillery-update.plist     |  38 +++
 .../templates/launchd/local.distillery.plist  |  36 +++
 scripts/local-macos/templates/maintenance.sh  |   9 +
 scripts/local-macos/templates/poll.sh         |  10 +
 scripts/local-macos/templates/rescore.sh      |   7 +
 scripts/local-macos/templates/run.sh          |  51 ++++
 scripts/local-macos/templates/update.sh       |  45 ++++
 scripts/local-macos/uninstall.sh              | 122 +++++++++
 19 files changed, 997 insertions(+)
 create mode 100644 docs/getting-started/local-macos.md
 create mode 100644 scripts/local-macos/README.md
 create mode 100755 scripts/local-macos/install.sh
 create mode 100644 scripts/local-macos/templates/_webhook_common.sh
 create mode 100644 scripts/local-macos/templates/classify.sh
 create mode 100644 scripts/local-macos/templates/distillery.yaml
 create mode 100644 scripts/local-macos/templates/launchd/local.distillery-classify.plist
 create mode 100644 scripts/local-macos/templates/launchd/local.distillery-maintenance.plist
 create mode 100644 scripts/local-macos/templates/launchd/local.distillery-poll.plist
 create mode 100644 scripts/local-macos/templates/launchd/local.distillery-rescore.plist
 create mode 100644 scripts/local-macos/templates/launchd/local.distillery-update.plist
 create mode 100644 scripts/local-macos/templates/launchd/local.distillery.plist
 create mode 100644 scripts/local-macos/templates/maintenance.sh
 create mode 100644 scripts/local-macos/templates/poll.sh
 create mode 100644 scripts/local-macos/templates/rescore.sh
 create mode 100644 scripts/local-macos/templates/run.sh
 create mode 100644 scripts/local-macos/templates/update.sh
 create mode 100755 scripts/local-macos/uninstall.sh

diff --git a/docs/getting-started/local-macos.md b/docs/getting-started/local-macos.md
new file mode 100644
index 00000000..80220617
--- /dev/null
+++ b/docs/getting-started/local-macos.md
@@ -0,0 +1,166 @@
+# Local macOS (launchd)
+
+Runs a supervised Distillery server on your Mac with scheduled ingestion, image updates, and maintenance — zero cloud, zero CI. Installed by `scripts/local-macos/install.sh`.
+
+This is a different profile from the [stdio local setup](local-setup.md):
+
+| | stdio (`local-setup.md`) | launchd (this page) |
+|---|---|---|
+| Transport | stdio | HTTP on `127.0.0.1:8000` |
+| Lifecycle | launched per Claude Code session | supervised daemon, runs 24/7 |
+| Scheduled work | optional Claude Code routines | six LaunchAgents |
+| Image updates | manual | weekly auto-pull |
+| Good for | single-user, low-footprint | heavier feed ingestion, personal KB |
+
+## What gets installed
+
+Six LaunchAgents in `~/Library/LaunchAgents/`:
+
+| Label | Cadence | Purpose |
+|---|---|---|
+| `local.distillery` | supervised | Runs the GHCR container (`ghcr.io/norrietaylor/distillery:latest`) in the foreground; launchd restarts it on exit. |
+| `local.distillery-update` | Mondays 09:00 | `docker pull` the `:latest` image; if the digest changed, kickstart the server. |
+| `local.distillery-poll` | every 30 min | `POST /api/poll` — fetch new items from configured feed sources. |
+| `local.distillery-classify` | every 2 hours | `POST /api/hooks/classify-batch` — batch-classify pending inbox entries. |
+| `local.distillery-rescore` | daily 04:15 | `POST /api/rescore` — refresh feed-entry relevance scores. |
+| `local.distillery-maintenance` | Mondays 05:00 | `POST /api/maintenance` — orchestrated `poll → rescore → classify-batch`. |
+
+Plus these files in `~/.distillery/`:
+
+- `distillery.yaml` — server config
+- `run.sh`, `update.sh` — server supervisor + image-update worker
+- `poll.sh`, `classify.sh`, `rescore.sh`, `maintenance.sh` — webhook workers
+- `_webhook_common.sh` — shared helper sourced by the four workers
+- `distillery.db` — the DuckDB file
+- `*.log` — per-agent stdout/stderr
+
+And two entries in the macOS login Keychain (`security` CLI):
+
+- `JINA_API_KEY` — embedding provider key
+- `DISTILLERY_WEBHOOK_SECRET` — bearer token for `/api/*` routes
+
+## Prerequisites
+
+- macOS (tested on Sonoma and later)
+- [OrbStack](https://orbstack.dev) *or* Docker Desktop, running
+- A free [Jina AI](https://jina.ai) API key
+
+Docker on Apple Silicon runs the container under Rosetta (`linux/amd64`). No separate arm64 image is published.
+
+## Install
+
+```bash
+git clone https://github.com/norrietaylor/distillery.git
+cd distillery
+./scripts/local-macos/install.sh
+```
+
+The installer will:
+
+1. Verify Docker is reachable.
+2. Prompt for your Jina API key (skipped if already in the Keychain).
+3. Generate a 32-byte webhook bearer secret (skipped if already in the Keychain).
+4. Write the config, scripts, and plists.
+5. Bootstrap every agent and kickstart the server.
+6. Wait up to 30 s for `http://127.0.0.1:8000/` to respond.
+
+Re-run any time to refresh scripts/plists — the installer is idempotent and never touches the database or existing secrets.
+
+### Flags
+
+| Flag | Effect |
+|---|---|
+| `--jina-key <value>` | Pass the Jina key non-interactively (useful for scripted installs). |
+| `--no-kickstart` | Load the agents but don't start the server or poll for readiness. |
+
+## Point Claude Code at the server
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "distillery": {
+      "type": "http",
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code, then run `/setup` — it will detect the running server and offer to configure the reporting routines (feed health check, stale check, weekly digest). Those routines run inside Claude Code and complement the ingestion agents installed here.
+
+## Verify
+
+```bash
+# All six agents loaded
+launchctl list | grep distillery
+
+# Kick the server in case it's not running
+launchctl kickstart -k gui/$(id -u)/local.distillery
+
+# Server is up
+curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/
+
+# Webhook auth works (expects 202 Accepted)
+SECRET=$(security find-generic-password -a "$USER" -s DISTILLERY_WEBHOOK_SECRET -w)
+curl -sS -H "Authorization: Bearer $SECRET" -X POST http://127.0.0.1:8000/api/poll
+```
+
+Tail the logs to watch the agents fire:
+
+```bash
+tail -F ~/.distillery/{poll,classify,rescore,maintenance}.out.log
+```
+
+## Customizing
+
+### Change the cadence
+
+Edit the `StartInterval` (seconds) or `StartCalendarInterval` block in the plist, then reload:
+
+```bash
+launchctl bootout gui/$(id -u)/local.distillery-poll
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.distillery-poll.plist
+```
+
+### Rotate the webhook secret
+
+```bash
+security delete-generic-password -a "$USER" -s DISTILLERY_WEBHOOK_SECRET
+./scripts/local-macos/install.sh     # regenerates on next install
+launchctl kickstart -k gui/$(id -u)/local.distillery
+```
+
+### Add a feed source
+
+Open Claude Code and run `/watch add <url>`, or call `distillery_watch` directly via the MCP.
+
+### Disable one pipeline
+
+```bash
+launchctl bootout gui/$(id -u)/local.distillery-rescore
+rm ~/Library/LaunchAgents/local.distillery-rescore.plist
+```
+
+## Troubleshooting
+
+**Webhook returns 401.** The server didn't see `DISTILLERY_WEBHOOK_SECRET` at startup — check the Keychain entry exists, then `launchctl kickstart -k gui/$(id -u)/local.distillery`.
+
+**Webhook returns 429 "too_early".** Per-endpoint cooldown. The worker treats this as success; nothing to fix.
+
+**Container won't start.** Inspect `~/.distillery/server.err.log`. The supervisor exits 1 if `JINA_API_KEY` or `DISTILLERY_WEBHOOK_SECRET` is missing from the Keychain — launchd respects `ThrottleInterval=10` so it retries every 10 s.
+
+**`IO Error: Conflicting lock`.** Something other than the server is trying to open the DuckDB file (`docker exec ... distillery <cmd>`, a second container, a CLI on the host). DuckDB is single-writer; only the running server process may open the DB for writes. Use the HTTP webhooks instead.
+
+**Agents silently not firing.** `launchctl print gui/$(id -u)/<label>` shows the next fire time and the last exit status. For calendar-based agents, confirm the Mac was awake at the scheduled minute — `StartCalendarIntervalRunOnMissed=true` triggers a catch-up on next wake.
+
+## Uninstall
+
+```bash
+./scripts/local-macos/uninstall.sh                       # unload agents, remove files
+./scripts/local-macos/uninstall.sh --purge-data          # + delete DB, config, logs
+./scripts/local-macos/uninstall.sh --purge-secrets       # + delete Keychain entries
+```
+
+Default uninstall preserves the database and Keychain entries so a re-install is non-destructive.
diff --git a/mkdocs.yml b/mkdocs.yml
index 832cd0e6..880cc5ec 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -64,6 +64,7 @@ nav:
   - Getting Started:
     - Plugin Install: getting-started/plugin-install.md
     - Local Setup: getting-started/local-setup.md
+    - Local macOS (launchd): getting-started/local-macos.md
     - MCP Server Reference: getting-started/mcp-setup.md
   - Skills Reference:
     - Overview: skills/index.md
diff --git a/scripts/local-macos/README.md b/scripts/local-macos/README.md
new file mode 100644
index 00000000..fbbc5c17
--- /dev/null
+++ b/scripts/local-macos/README.md
@@ -0,0 +1,48 @@
+# Local macOS launchd setup
+
+One-shot installer for running a self-hosted Distillery server on macOS with
+supervised lifecycle and scheduled ingestion pipelines.
+
+## What it installs
+
+| LaunchAgent | Cadence | What it does |
+|---|---|---|
+| `local.distillery` | supervised | runs the GHCR container in the foreground; restarts on exit |
+| `local.distillery-update` | Mon 09:00 | pulls `:latest`; restarts the server if the digest changed |
+| `local.distillery-poll` | every 30 min | `POST /api/poll` — ingest new feed items |
+| `local.distillery-classify` | every 2 h | `POST /api/hooks/classify-batch` — drain the inbox |
+| `local.distillery-rescore` | daily 04:15 | `POST /api/rescore` — refresh relevance scores |
+| `local.distillery-maintenance` | Mon 05:00 | `POST /api/maintenance` — full pipeline (poll → rescore → classify) |
+
+All ingestion goes through the running server's HTTP surface, not a sibling
+CLI process — DuckDB is single-writer, and the server holds the write lock.
+
+## Install
+
+```bash
+./install.sh
+```
+
+The installer:
+
+1. Verifies Docker (OrbStack or Docker Desktop) is reachable.
+2. Reads or prompts for a Jina API key; stores it in the login Keychain.
+3. Generates a 32-byte webhook bearer secret; stores it in the Keychain.
+4. Writes `~/.distillery/{distillery.yaml,*.sh}` and six plists in
+   `~/Library/LaunchAgents/`.
+5. Bootstraps each agent and kickstarts the server.
+
+It's idempotent — re-running refreshes scripts and plists without touching
+the DB or existing secrets.
+
+## Uninstall
+
+```bash
+./uninstall.sh                           # unload agents, remove scripts/plists/container
+./uninstall.sh --purge-data              # also delete distillery.yaml + DB + logs
+./uninstall.sh --purge-secrets           # also delete Keychain entries
+```
+
+## See also
+
+Full walkthrough: [docs/getting-started/local-macos.md](../../docs/getting-started/local-macos.md).
diff --git a/scripts/local-macos/install.sh b/scripts/local-macos/install.sh
new file mode 100755
index 00000000..beb34332
--- /dev/null
+++ b/scripts/local-macos/install.sh
@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# Install the Distillery local macOS setup:
+#   • supervised server container (GHCR image) via launchd
+#   • weekly image-update agent
+#   • four scheduled webhook agents: poll / classify / rescore / maintenance
+#
+# Safe to re-run; reinstalls scripts, rewrites plists, reloads agents.
+# Does not destroy the DuckDB file or existing Keychain entries.
+#
+# Usage:
+#   ./install.sh              # interactive
+#   ./install.sh --jina-key "jina_..."
+#   ./install.sh --no-kickstart   # install but don't start agents
+#
+# The generated webhook bearer secret is created on first run only; subsequent
+# runs leave it alone. Delete it with `security delete-generic-password
+# -a "$USER" -s DISTILLERY_WEBHOOK_SECRET` to rotate.
+
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
+TEMPLATES=$SCRIPT_DIR/templates
+
+DATA_DIR=$HOME/.distillery
+LAUNCHAGENTS=$HOME/Library/LaunchAgents
+
+JINA_KEY_CLI=""
+DO_KICKSTART=1
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --jina-key)       JINA_KEY_CLI="$2"; shift 2 ;;
+    --no-kickstart)   DO_KICKSTART=0; shift ;;
+    -h|--help)
+      sed -n '2,20p' "$0"
+      exit 0
+      ;;
+    *) echo "unknown flag: $1" >&2; exit 2 ;;
+  esac
+done
+
+log() { printf '  %s\n' "$*"; }
+bold() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "missing required command: $1" >&2
+    exit 1
+  }
+}
+
+# ---- preflight --------------------------------------------------------------
+
+bold "Preflight"
+
+if [ "$(uname -s)" != "Darwin" ]; then
+  echo "this installer is macOS-only (uname=$(uname -s))" >&2
+  exit 1
+fi
+log "macOS detected"
+
+require security
+require launchctl
+require curl
+require python3
+log "security / launchctl / curl / python3 available"
+
+# Locate docker binary. OrbStack installs to ~/.orbstack/bin; Docker Desktop
+# installs to /usr/local/bin. Prefer whichever `docker` is on PATH; fall back
+# to the common install locations.
+DOCKER=""
+for candidate in "$(command -v docker 2>/dev/null || true)" \
+                 "$HOME/.orbstack/bin/docker" \
+                 "/usr/local/bin/docker" \
+                 "/opt/homebrew/bin/docker"; do
+  if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+    DOCKER=$candidate
+    break
+  fi
+done
+if [ -z "$DOCKER" ]; then
+  echo "docker not found — install OrbStack (https://orbstack.dev) or Docker Desktop" >&2
+  exit 1
+fi
+log "docker: $DOCKER"
+
+DOCKER_DIR=$(dirname "$DOCKER")
+
+if ! "$DOCKER" info >/dev/null 2>&1; then
+  echo "docker daemon is not running — start OrbStack/Docker Desktop and re-run" >&2
+  exit 1
+fi
+log "docker daemon reachable"
+
+# ---- secrets ----------------------------------------------------------------
+
+bold "Secrets (login Keychain)"
+
+# Jina API key: keep existing entry, or accept --jina-key, or prompt.
+if security find-generic-password -a "$USER" -s JINA_API_KEY -w >/dev/null 2>&1; then
+  log "JINA_API_KEY: already in Keychain (keeping existing value)"
+else
+  if [ -z "$JINA_KEY_CLI" ]; then
+    echo
+    read -r -s -p "  Jina API key (free tier at https://jina.ai) [paste, not echoed]: " JINA_KEY_CLI
+    echo
+  fi
+  if [ -z "$JINA_KEY_CLI" ]; then
+    echo "JINA_API_KEY is required" >&2
+    exit 1
+  fi
+  security add-generic-password -a "$USER" -s JINA_API_KEY -w "$JINA_KEY_CLI" -U
+  log "JINA_API_KEY: stored"
+fi
+
+# Webhook bearer secret: generate once, then leave alone.
+if security find-generic-password -a "$USER" -s DISTILLERY_WEBHOOK_SECRET -w >/dev/null 2>&1; then
+  log "DISTILLERY_WEBHOOK_SECRET: already in Keychain (keeping existing value)"
+else
+  SECRET=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')
+  security add-generic-password -a "$USER" -s DISTILLERY_WEBHOOK_SECRET -w "$SECRET" -U
+  log "DISTILLERY_WEBHOOK_SECRET: generated and stored"
+fi
+
+# ---- data dir + config ------------------------------------------------------
+
+bold "Data directory"
+
+mkdir -p "$DATA_DIR"
+log "ensured $DATA_DIR"
+
+if [ -f "$DATA_DIR/distillery.yaml" ]; then
+  log "distillery.yaml: already present (keeping existing; compare against $TEMPLATES/distillery.yaml for changes)"
+else
+  cp "$TEMPLATES/distillery.yaml" "$DATA_DIR/distillery.yaml"
+  log "distillery.yaml: installed"
+fi
+
+# ---- scripts ----------------------------------------------------------------
+
+bold "Scripts"
+
+install_script() {
+  local src="$1" dst="$2"
+  # Substitute the detected docker path into any __DOCKER__ placeholder.
+  sed -e "s|__DOCKER__|$DOCKER|g" "$src" >"$dst"
+  chmod +x "$dst"
+  log "$(basename "$dst")"
+}
+
+install_script "$TEMPLATES/run.sh"              "$DATA_DIR/run.sh"
+install_script "$TEMPLATES/update.sh"           "$DATA_DIR/update.sh"
+install_script "$TEMPLATES/_webhook_common.sh"  "$DATA_DIR/_webhook_common.sh"
+install_script "$TEMPLATES/poll.sh"             "$DATA_DIR/poll.sh"
+install_script "$TEMPLATES/classify.sh"         "$DATA_DIR/classify.sh"
+install_script "$TEMPLATES/rescore.sh"          "$DATA_DIR/rescore.sh"
+install_script "$TEMPLATES/maintenance.sh"      "$DATA_DIR/maintenance.sh"
+
+# ---- LaunchAgents -----------------------------------------------------------
+
+bold "LaunchAgents"
+
+mkdir -p "$LAUNCHAGENTS"
+
+install_plist() {
+  local label="$1"
+  local src="$TEMPLATES/launchd/${label}.plist"
+  local dst="$LAUNCHAGENTS/${label}.plist"
+  sed -e "s|__HOME__|$HOME|g" \
+      -e "s|__DOCKER_DIR__|$DOCKER_DIR|g" \
+      "$src" >"$dst"
+  log "$(basename "$dst")"
+}
+
+AGENTS=(
+  local.distillery
+  local.distillery-update
+  local.distillery-poll
+  local.distillery-classify
+  local.distillery-rescore
+  local.distillery-maintenance
+)
+
+for label in "${AGENTS[@]}"; do
+  install_plist "$label"
+done
+
+# ---- load + start -----------------------------------------------------------
+
+bold "Load agents"
+
+UID_NUM=$(id -u)
+for label in "${AGENTS[@]}"; do
+  plist="$LAUNCHAGENTS/${label}.plist"
+  # Bootout first so re-installs pick up changes, then bootstrap.
+  launchctl bootout "gui/$UID_NUM/$label" >/dev/null 2>&1 || true
+  launchctl bootstrap "gui/$UID_NUM" "$plist"
+  log "$label: loaded"
+done
+
+if [ "$DO_KICKSTART" -eq 1 ]; then
+  bold "Verify"
+  launchctl kickstart -k "gui/$UID_NUM/local.distillery" >/dev/null 2>&1 || true
+  log "server kickstarted; waiting for http://127.0.0.1:8000 ..."
+
+  ready=0
+  for _ in $(seq 1 30); do
+    if curl -sS --max-time 2 -o /dev/null "http://127.0.0.1:8000/" 2>/dev/null; then
+      ready=1; break
+    fi
+    sleep 1
+  done
+  if [ "$ready" -eq 1 ]; then
+    log "server is responding"
+  else
+    log "server did not respond within 30s — check $DATA_DIR/server.err.log"
+  fi
+fi
+
+bold "Done"
+cat <<EOF
+  Data dir:       $DATA_DIR
+  LaunchAgents:   $LAUNCHAGENTS/local.distillery*.plist
+  Logs:           $DATA_DIR/*.log
+  Uninstall:      $SCRIPT_DIR/uninstall.sh
+
+Point Claude Code at the server by adding to ~/.claude/settings.json:
+
+  {
+    "mcpServers": {
+      "distillery": {
+        "type": "http",
+        "url": "http://127.0.0.1:8000/mcp"
+      }
+    }
+  }
+
+Then run /setup inside Claude Code to configure the reporting routines.
+EOF
diff --git a/scripts/local-macos/templates/_webhook_common.sh b/scripts/local-macos/templates/_webhook_common.sh
new file mode 100644
index 00000000..600b5dbb
--- /dev/null
+++ b/scripts/local-macos/templates/_webhook_common.sh
@@ -0,0 +1,46 @@
+#!/bin/zsh
+# Shared helpers for the webhook worker scripts (poll.sh, classify.sh,
+# rescore.sh, maintenance.sh). Source this file; do not execute directly.
+#
+# Usage:
+#   source "$HOME/.distillery/_webhook_common.sh"
+#   call_webhook <name> <url> <timeout_seconds> <ok_codes_regex>
+
+SERVER_BASE="http://127.0.0.1:8000"
+
+call_webhook() {
+  local name="$1"
+  local url="$2"
+  local timeout="$3"
+  local ok_re="$4"   # anchored regex, e.g. '^(200|202|409|429)$'
+
+  local secret
+  secret=$(security find-generic-password -a "$USER" -s DISTILLERY_WEBHOOK_SECRET -w 2>/dev/null || true)
+  if [ -z "$secret" ]; then
+    echo "[$(date -Iseconds)] DISTILLERY_WEBHOOK_SECRET not in Keychain; skipping $name" >&2
+    return 0
+  fi
+
+  # Bail quietly if the server is unreachable — launchd will retry on schedule.
+  if ! curl -sS --max-time 5 -o /dev/null -w '%{http_code}' "$SERVER_BASE/" 2>/dev/null \
+       | grep -Eq '^[2345]'; then
+    echo "[$(date -Iseconds)] server at $SERVER_BASE unreachable; skipping $name" >&2
+    return 0
+  fi
+
+  local ts resp code body
+  ts=$(date -Iseconds)
+  resp=$(curl -sS --max-time "$timeout" \
+    -H "Authorization: Bearer $secret" \
+    -w '\n%{http_code}' \
+    -X POST "$url" || true)
+  code=$(printf '%s' "$resp" | tail -n1)
+  body=$(printf '%s' "$resp" | sed '$d')
+
+  if printf '%s' "$code" | grep -Eq "$ok_re"; then
+    echo "[$ts] $name $code $body"
+    return 0
+  fi
+  echo "[$ts] $name FAILED $code $body" >&2
+  return 1
+}
diff --git a/scripts/local-macos/templates/classify.sh b/scripts/local-macos/templates/classify.sh
new file mode 100644
index 00000000..aef7733d
--- /dev/null
+++ b/scripts/local-macos/templates/classify.sh
@@ -0,0 +1,8 @@
+#!/bin/zsh
+# Launched by ~/Library/LaunchAgents/local.distillery-classify.plist every 2h.
+# Batch-classifies pending inbox entries via POST /api/hooks/classify-batch.
+# That endpoint is synchronous and returns 200 with a summary body.
+
+set -eu
+source "$HOME/.distillery/_webhook_common.sh"
+call_webhook classify "$SERVER_BASE/api/hooks/classify-batch" 120 '^(200|202)$'
diff --git a/scripts/local-macos/templates/distillery.yaml b/scripts/local-macos/templates/distillery.yaml
new file mode 100644
index 00000000..c7a05cfc
--- /dev/null
+++ b/scripts/local-macos/templates/distillery.yaml
@@ -0,0 +1,40 @@
+# Distillery config for the local macOS launchd install.
+# Mounted into the container at /data/distillery.yaml (DISTILLERY_CONFIG).
+
+storage:
+  backend: duckdb
+  database_path: /data/distillery.db
+
+embedding:
+  provider: jina
+  model: jina-embeddings-v3
+  dimensions: 1024
+  api_key_env: JINA_API_KEY
+
+team:
+  name: distillery-local
+
+server:
+  # The container is bound to 127.0.0.1 on the host; no external exposure.
+  auth:
+    provider: none
+  webhooks:
+    enabled: true
+    secret_env: DISTILLERY_WEBHOOK_SECRET
+
+classification:
+  confidence_threshold: 0.6
+  dedup_skip_threshold: 0.95
+  dedup_merge_threshold: 0.80
+  dedup_link_threshold: 0.60
+  dedup_limit: 5
+
+feeds:
+  thresholds:
+    alert: 0.85
+    digest: 0.60
+  sources: []
+
+tags:
+  enforce_namespaces: false
+  reserved_prefixes: []
diff --git a/scripts/local-macos/templates/launchd/local.distillery-classify.plist b/scripts/local-macos/templates/launchd/local.distillery-classify.plist
new file mode 100644
index 00000000..c5537164
--- /dev/null
+++ b/scripts/local-macos/templates/launchd/local.distillery-classify.plist
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>local.distillery-classify</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HOME__/.distillery/classify.sh</string>
+    </array>
+
+    <!-- Every 2 hours. -->
+    <key>StartInterval</key>
+    <integer>7200</integer>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.distillery/classify.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.distillery/classify.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>
diff --git a/scripts/local-macos/templates/launchd/local.distillery-maintenance.plist b/scripts/local-macos/templates/launchd/local.distillery-maintenance.plist
new file mode 100644
index 00000000..70991490
--- /dev/null
+++ b/scripts/local-macos/templates/launchd/local.distillery-maintenance.plist
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>local.distillery-maintenance</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HOME__/.distillery/maintenance.sh</string>
+    </array>
+
+    <!-- Mondays at 05:00 local time — runs before the 09:00 image-update
+         agent so pipeline work completes against the current image. -->
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Weekday</key>
+        <integer>1</integer>
+        <key>Hour</key>
+        <integer>5</integer>
+        <key>Minute</key>
+        <integer>0</integer>
+    </dict>
+
+    <key>StartCalendarIntervalRunOnMissed</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.distillery/maintenance.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.distillery/maintenance.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>
diff --git a/scripts/local-macos/templates/launchd/local.distillery-poll.plist b/scripts/local-macos/templates/launchd/local.distillery-poll.plist
new file mode 100644
index 00000000..a0204e14
--- /dev/null
+++ b/scripts/local-macos/templates/launchd/local.distillery-poll.plist
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>local.distillery-poll</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HOME__/.distillery/poll.sh</string>
+    </array>
+
+    <!-- Every 30 minutes. -->
+    <key>StartInterval</key>
+    <integer>1800</integer>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.distillery/poll.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.distillery/poll.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>
diff --git a/scripts/local-macos/templates/launchd/local.distillery-rescore.plist b/scripts/local-macos/templates/launchd/local.distillery-rescore.plist
new file mode 100644
index 00000000..bc458281
--- /dev/null
+++ b/scripts/local-macos/templates/launchd/local.distillery-rescore.plist
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>local.distillery-rescore</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HOME__/.distillery/rescore.sh</string>
+    </array>
+
+    <!-- Daily at 04:15 local time. -->
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>4</integer>
+        <key>Minute</key>
+        <integer>15</integer>
+    </dict>
+
+    <key>StartCalendarIntervalRunOnMissed</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.distillery/rescore.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.distillery/rescore.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>
diff --git a/scripts/local-macos/templates/launchd/local.distillery-update.plist b/scripts/local-macos/templates/launchd/local.distillery-update.plist
new file mode 100644
index 00000000..4028dd41
--- /dev/null
+++ b/scripts/local-macos/templates/launchd/local.distillery-update.plist
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>local.distillery-update</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HOME__/.distillery/update.sh</string>
+    </array>
+
+    <!-- Mondays at 09:00 local time. -->
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Weekday</key>
+        <integer>1</integer>
+        <key>Hour</key>
+        <integer>9</integer>
+        <key>Minute</key>
+        <integer>0</integer>
+    </dict>
+
+    <key>StartCalendarIntervalRunOnMissed</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.distillery/update.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.distillery/update.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>__DOCKER_DIR__:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>
diff --git a/scripts/local-macos/templates/launchd/local.distillery.plist b/scripts/local-macos/templates/launchd/local.distillery.plist
new file mode 100644
index 00000000..23162afe
--- /dev/null
+++ b/scripts/local-macos/templates/launchd/local.distillery.plist
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>local.distillery</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HOME__/.distillery/run.sh</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.distillery/server.log</string>
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.distillery/server.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>__DOCKER_DIR__:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>
diff --git a/scripts/local-macos/templates/maintenance.sh b/scripts/local-macos/templates/maintenance.sh
new file mode 100644
index 00000000..2791cdf2
--- /dev/null
+++ b/scripts/local-macos/templates/maintenance.sh
@@ -0,0 +1,9 @@
+#!/bin/zsh
+# Launched by ~/Library/LaunchAgents/local.distillery-maintenance.plist weekly.
+# Runs the orchestrated pipeline (poll -> rescore -> classify-batch) via
+# POST /api/maintenance. Safe to run alongside the per-job agents; the
+# server's per-endpoint cooldowns coalesce overlapping work.
+
+set -eu
+source "$HOME/.distillery/_webhook_common.sh"
+call_webhook maintenance "$SERVER_BASE/api/maintenance" 30 '^(202|409|429)$'
diff --git a/scripts/local-macos/templates/poll.sh b/scripts/local-macos/templates/poll.sh
new file mode 100644
index 00000000..3b5d683f
--- /dev/null
+++ b/scripts/local-macos/templates/poll.sh
@@ -0,0 +1,10 @@
+#!/bin/zsh
+# Launched by ~/Library/LaunchAgents/local.distillery-poll.plist every 30 min.
+# Polls configured feed sources via POST /api/poll. The running server owns
+# the DuckDB write lock, so ingestion must go through its HTTP surface.
+#
+# 202 = accepted, 409 = job already in flight, 429 = cooldown not elapsed.
+
+set -eu
+source "$HOME/.distillery/_webhook_common.sh"
+call_webhook poll "$SERVER_BASE/api/poll" 20 '^(202|409|429)$'
diff --git a/scripts/local-macos/templates/rescore.sh b/scripts/local-macos/templates/rescore.sh
new file mode 100644
index 00000000..ecb4c30a
--- /dev/null
+++ b/scripts/local-macos/templates/rescore.sh
@@ -0,0 +1,7 @@
+#!/bin/zsh
+# Launched by ~/Library/LaunchAgents/local.distillery-rescore.plist daily.
+# Recomputes relevance scores for stored feed entries via POST /api/rescore.
+
+set -eu
+source "$HOME/.distillery/_webhook_common.sh"
+call_webhook rescore "$SERVER_BASE/api/rescore" 20 '^(202|409|429)$'
diff --git a/scripts/local-macos/templates/run.sh b/scripts/local-macos/templates/run.sh
new file mode 100644
index 00000000..e6d26eb5
--- /dev/null
+++ b/scripts/local-macos/templates/run.sh
@@ -0,0 +1,51 @@
+#!/bin/zsh
+# Launched by ~/Library/LaunchAgents/local.distillery.plist.
+# Runs the Distillery MCP server (GHCR image) in the foreground so launchd
+# can supervise it and restart on exit.
+
+set -eu
+
+DOCKER="__DOCKER__"
+IMAGE=ghcr.io/norrietaylor/distillery:latest
+PLATFORM=linux/amd64        # no arm64 manifest on GHCR; runs under Rosetta
+NAME=distillery
+DATA_DIR=$HOME/.distillery
+PORT=8000
+
+# OrbStack / Docker Desktop auto-start on demand; give the daemon a moment
+# to come up on cold boot before we bail.
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if "$DOCKER" info >/dev/null 2>&1; then break; fi
+  sleep 2
+done
+
+JINA_API_KEY=$(security find-generic-password -a "$USER" -s JINA_API_KEY -w 2>/dev/null || true)
+if [ -z "${JINA_API_KEY}" ]; then
+  echo "JINA_API_KEY not found in Keychain (service=JINA_API_KEY)." >&2
+  echo "  security add-generic-password -a \"$USER\" -s JINA_API_KEY -w <key> -U" >&2
+  exit 1
+fi
+
+DISTILLERY_WEBHOOK_SECRET=$(security find-generic-password -a "$USER" -s DISTILLERY_WEBHOOK_SECRET -w 2>/dev/null || true)
+if [ -z "${DISTILLERY_WEBHOOK_SECRET}" ]; then
+  echo "DISTILLERY_WEBHOOK_SECRET not found in Keychain (service=DISTILLERY_WEBHOOK_SECRET)." >&2
+  echo "  security add-generic-password -a \"$USER\" -s DISTILLERY_WEBHOOK_SECRET \\" >&2
+  echo "    -w \"\$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')\" -U" >&2
+  exit 1
+fi
+
+# Clean up any prior instance (stale after crash, reboot, or image swap).
+"$DOCKER" rm -f "$NAME" >/dev/null 2>&1 || true
+
+exec "$DOCKER" run \
+  --rm \
+  --name "$NAME" \
+  --platform "$PLATFORM" \
+  -p 127.0.0.1:${PORT}:8000 \
+  -v "$DATA_DIR":/data \
+  -e DISTILLERY_CONFIG=/data/distillery.yaml \
+  -e JINA_API_KEY="$JINA_API_KEY" \
+  -e DISTILLERY_WEBHOOK_SECRET="$DISTILLERY_WEBHOOK_SECRET" \
+  -e DISTILLERY_HOST=0.0.0.0 \
+  -e DISTILLERY_PORT=8000 \
+  "$IMAGE"
diff --git a/scripts/local-macos/templates/update.sh b/scripts/local-macos/templates/update.sh
new file mode 100644
index 00000000..777175b2
--- /dev/null
+++ b/scripts/local-macos/templates/update.sh
@@ -0,0 +1,45 @@
+#!/bin/zsh
+# Launched by ~/Library/LaunchAgents/local.distillery-update.plist.
+# Pulls ghcr.io/norrietaylor/distillery:latest; if the image changed,
+# restarts the server and records the delta in ~/.distillery/update.log.
+
+set -eu
+
+DOCKER="__DOCKER__"
+IMAGE=ghcr.io/norrietaylor/distillery:latest
+PLATFORM=linux/amd64
+LOG=$HOME/.distillery/update.log
+
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if "$DOCKER" info >/dev/null 2>&1; then break; fi
+  sleep 2
+done
+
+OLD_SHA=$("$DOCKER" image inspect "$IMAGE" \
+  --format '{{range .Config.Env}}{{println .}}{{end}}' 2>/dev/null \
+  | awk -F= '/^DISTILLERY_BUILD_SHA=/{print $2}') || OLD_SHA=""
+OLD_DIGEST=$("$DOCKER" image inspect "$IMAGE" --format '{{.Id}}' 2>/dev/null || true)
+
+"$DOCKER" pull --platform "$PLATFORM" --quiet "$IMAGE" >/dev/null
+
+NEW_SHA=$("$DOCKER" image inspect "$IMAGE" \
+  --format '{{range .Config.Env}}{{println .}}{{end}}' \
+  | awk -F= '/^DISTILLERY_BUILD_SHA=/{print $2}')
+NEW_DIGEST=$("$DOCKER" image inspect "$IMAGE" --format '{{.Id}}')
+
+TS=$(date -Iseconds)
+
+if [ "$OLD_DIGEST" = "$NEW_DIGEST" ]; then
+  echo "[$TS] no change (digest $NEW_DIGEST, build $NEW_SHA)" >> "$LOG"
+  exit 0
+fi
+
+{
+  echo "[$TS] image updated"
+  echo "  old build: ${OLD_SHA:-<none>}   digest: ${OLD_DIGEST:-<none>}"
+  echo "  new build: ${NEW_SHA}             digest: ${NEW_DIGEST}"
+} >> "$LOG"
+
+# Restart the server so it picks up the new image.
+launchctl kickstart -k "gui/$(id -u)/local.distillery" >/dev/null 2>&1 || true
+echo "  restarted local.distillery" >> "$LOG"
diff --git a/scripts/local-macos/uninstall.sh b/scripts/local-macos/uninstall.sh
new file mode 100755
index 00000000..82290954
--- /dev/null
+++ b/scripts/local-macos/uninstall.sh
@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Tear down the Distillery local macOS setup.
+#
+# Default behaviour:
+#   • Unload all local.distillery* LaunchAgents
+#   • Stop and remove the docker container
+#   • Remove plists from ~/Library/LaunchAgents
+#   • Remove scripts from ~/.distillery (run.sh, update.sh, *.sh workers,
+#     _webhook_common.sh)
+#
+# Preserved by default (destructive; requires explicit flags):
+#   --purge-data    also delete distillery.yaml, distillery.db, logs
+#   --purge-secrets also delete the Keychain entries (JINA_API_KEY,
+#                   DISTILLERY_WEBHOOK_SECRET)
+#
+# Examples:
+#   ./uninstall.sh
+#   ./uninstall.sh --purge-data
+#   ./uninstall.sh --purge-data --purge-secrets
+
+set -euo pipefail
+
+DATA_DIR=$HOME/.distillery
+LAUNCHAGENTS=$HOME/Library/LaunchAgents
+
+PURGE_DATA=0
+PURGE_SECRETS=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --purge-data)    PURGE_DATA=1; shift ;;
+    --purge-secrets) PURGE_SECRETS=1; shift ;;
+    -h|--help)
+      sed -n '2,20p' "$0"
+      exit 0
+      ;;
+    *) echo "unknown flag: $1" >&2; exit 2 ;;
+  esac
+done
+
+log() { printf '  %s\n' "$*"; }
+bold() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+
+AGENTS=(
+  local.distillery
+  local.distillery-update
+  local.distillery-poll
+  local.distillery-classify
+  local.distillery-rescore
+  local.distillery-maintenance
+)
+
+UID_NUM=$(id -u)
+
+bold "Unload agents"
+for label in "${AGENTS[@]}"; do
+  if launchctl print "gui/$UID_NUM/$label" >/dev/null 2>&1; then
+    launchctl bootout "gui/$UID_NUM/$label" >/dev/null 2>&1 || true
+    log "$label: unloaded"
+  else
+    log "$label: not loaded"
+  fi
+done
+
+bold "Remove container"
+DOCKER=$(command -v docker 2>/dev/null || true)
+[ -z "$DOCKER" ] && [ -x "$HOME/.orbstack/bin/docker" ] && DOCKER=$HOME/.orbstack/bin/docker
+if [ -n "$DOCKER" ] && "$DOCKER" info >/dev/null 2>&1; then
+  "$DOCKER" rm -f distillery >/dev/null 2>&1 || true
+  log "container 'distillery' removed (if present)"
+else
+  log "docker not reachable — skipped"
+fi
+
+bold "Remove plists"
+for label in "${AGENTS[@]}"; do
+  if [ -f "$LAUNCHAGENTS/${label}.plist" ]; then
+    rm -f "$LAUNCHAGENTS/${label}.plist"
+    log "${label}.plist: removed"
+  fi
+done
+
+bold "Remove scripts"
+for f in run.sh update.sh poll.sh classify.sh rescore.sh maintenance.sh _webhook_common.sh; do
+  if [ -f "$DATA_DIR/$f" ]; then
+    rm -f "$DATA_DIR/$f"
+    log "$f: removed"
+  fi
+done
+
+if [ "$PURGE_DATA" -eq 1 ]; then
+  bold "Purge data"
+  for f in distillery.yaml distillery.db distillery.db.wal \
+           server.log server.err.log update.log update.out.log update.err.log \
+           poll.out.log poll.err.log classify.out.log classify.err.log \
+           rescore.out.log rescore.err.log maintenance.out.log maintenance.err.log; do
+    if [ -e "$DATA_DIR/$f" ]; then
+      rm -f "$DATA_DIR/$f"
+      log "$f: removed"
+    fi
+  done
+  rmdir "$DATA_DIR" 2>/dev/null && log "$DATA_DIR: removed (empty)" || true
+fi
+
+if [ "$PURGE_SECRETS" -eq 1 ]; then
+  bold "Purge secrets"
+  for svc in JINA_API_KEY DISTILLERY_WEBHOOK_SECRET; do
+    if security delete-generic-password -a "$USER" -s "$svc" >/dev/null 2>&1; then
+      log "$svc: removed from Keychain"
+    else
+      log "$svc: not in Keychain"
+    fi
+  done
+fi
+
+bold "Done"
+if [ "$PURGE_DATA" -eq 0 ]; then
+  log "Data preserved in $DATA_DIR (pass --purge-data to delete)"
+fi
+if [ "$PURGE_SECRETS" -eq 0 ]; then
+  log "Keychain entries preserved (pass --purge-secrets to delete)"
+fi

From 1e0ed625aa07c4839eb66f97fd347ae071373716 Mon Sep 17 00:00:00 2001
From: norrietaylor <norrie@minimal.dev>
Date: Thu, 23 Apr 2026 22:30:40 -0700
Subject: [PATCH 2/3] fix(scripts): validate --jina-key has a value (coderabbit
 nitpick)

Previously, `./install.sh --jina-key` (with no following argument)
would silently accept an empty key under set -u or, worse, consume the
next flag. Reject both cases with a clear error and exit 2.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 scripts/local-macos/install.sh | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/scripts/local-macos/install.sh b/scripts/local-macos/install.sh
index beb34332..5ac329d6 100755
--- a/scripts/local-macos/install.sh
+++ b/scripts/local-macos/install.sh
@@ -29,7 +29,14 @@ DO_KICKSTART=1
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    --jina-key)       JINA_KEY_CLI="$2"; shift 2 ;;
+    --jina-key)
+      if [ $# -lt 2 ] || [[ "$2" == -* ]]; then
+        echo "--jina-key requires a value" >&2
+        exit 2
+      fi
+      JINA_KEY_CLI="$2"
+      shift 2
+      ;;
     --no-kickstart)   DO_KICKSTART=0; shift ;;
     -h|--help)
       sed -n '2,20p' "$0"

From 37ba75c79df237bbb342179f8ca2edd994ca8c7f Mon Sep 17 00:00:00 2001
From: norrietaylor <norrie@minimal.dev>
Date: Fri, 24 Apr 2026 14:07:27 -0700
Subject: [PATCH 3/3] fix(scripts): guard against sudo and remote docker
 contexts (coderabbit)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two preflight guards in the local-macOS installer:

- Refuse to run as root or under sudo. LaunchAgents and login-Keychain
  items are per-user; running under sudo would install them for root
  instead of the desktop user, producing a silently broken install.

- Reject remote docker contexts (ssh://, tcp://). `docker info` succeeds
  against a remote daemon, but the install binds the server to
  127.0.0.1:8000 on the daemon host — a remote daemon leaves the
  LaunchAgent workers unable to reach the server. Only unix:// contexts
  are accepted.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 scripts/local-macos/install.sh | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/scripts/local-macos/install.sh b/scripts/local-macos/install.sh
index 5ac329d6..a07e9f21 100755
--- a/scripts/local-macos/install.sh
+++ b/scripts/local-macos/install.sh
@@ -64,6 +64,11 @@ if [ "$(uname -s)" != "Darwin" ]; then
   echo "this installer is macOS-only (uname=$(uname -s))" >&2
   exit 1
 fi
+if [ "$(id -u)" -eq 0 ] || [ -n "${SUDO_USER:-}" ]; then
+  echo "run this installer as the logged-in macOS user, not with sudo/root" >&2
+  echo "  (LaunchAgents and login-Keychain items are per-user; sudo routes them to root)" >&2
+  exit 1
+fi
 log "macOS detected"
 
 require security
@@ -97,7 +102,20 @@ if ! "$DOCKER" info >/dev/null 2>&1; then
   echo "docker daemon is not running — start OrbStack/Docker Desktop and re-run" >&2
   exit 1
 fi
-log "docker daemon reachable"
+
+# Reject remote docker contexts (ssh://, tcp://) — the install binds the
+# server to 127.0.0.1:8000 on the docker host, so a remote daemon would
+# produce a "successful" install that the LaunchAgent workers can't reach.
+DOCKER_CONTEXT=$("$DOCKER" context show 2>/dev/null || true)
+DOCKER_HOST_URI=$("$DOCKER" context inspect "$DOCKER_CONTEXT" \
+  --format '{{.Endpoints.docker.Host}}' 2>/dev/null || true)
+if [ -n "$DOCKER_HOST_URI" ] && [[ "$DOCKER_HOST_URI" != unix://* ]]; then
+  echo "docker context '$DOCKER_CONTEXT' points to '$DOCKER_HOST_URI'" >&2
+  echo "  this installer needs a local daemon (unix://) — switch contexts and re-run" >&2
+  echo "  e.g. 'docker context use orbstack' or 'docker context use desktop-linux'" >&2
+  exit 1
+fi
+log "docker daemon reachable (context=${DOCKER_CONTEXT:-default})"
 
 # ---- secrets ----------------------------------------------------------------