create-egregore 0.19.7 → 0.19.11

package/runtime/pi/bin/publish-artifact.sh

@@ -95,6 +95,20 @@ fi
 # Public relay for OSS share endpoint
 RELAY_URL="https://egregore-production-55f2.up.railway.app"
 
+# --- Artifact hosting off-switch (compliance / privacy) ---
+# An instance can disable ALL egregore.xyz publishing via `bin/settings.sh hosting off`
+# (sets features.publishing=false). Absent/true means ON, so existing instances are
+# unaffected. We bail BEFORE any render or upload so "off" truly does nothing and costs
+# nothing. Exit 3 is distinct from usage errors; fire-and-forget callers ignore it.
+# NOTE: test `!= false`, not jq's `// "true"` — `//` treats an explicit `false` as empty
+# and would return the default, silently defeating the off-switch.
+PUBLISHING_ENABLED="$(jq -r 'if .features.publishing == false then "false" else "true" end' "$CONFIG" 2>/dev/null || echo "true")"
+if [ "$PUBLISHING_ENABLED" = "false" ]; then
+  echo "Artifact hosting is off for this egregore (features.publishing=false); nothing uploaded." >&2
+  echo "Turn it on with: bin/settings.sh hosting on   (or: egregore settings → Hosting)." >&2
+  exit 3
+fi
+
 # --- Prepare HTML ---
 TMP_HTML="/tmp/egregore-artifacts/publish-$$.html"
 mkdir -p /tmp/egregore-artifacts

package/runtime/pi/bin/session-autosave.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+# session-autosave.sh — save non-coding session work without an explicit /save.
+#
+# Terminal-close is the design constraint: no single "session end" event is
+# reliable (people just close the window), so durability comes from three
+# overlapping triggers:
+#   - Stop hook, debounced (Claude Code): saves DURING the session, after a
+#     turn completes — a killed terminal loses at most the debounce window.
+#   - Session-start sweep (--sweep, all runtimes): the next launch on this
+#     machine rescues leftovers in the main checkout and lingering worktrees.
+#   - SessionEnd hook / agent.sh wrap (Codex, Pi): immediate save on clean exit.
+#
+# Gate: acts ONLY when every pending change — uncommitted files AND commits
+# ahead of origin/develop — is non-coding per bin/lib/noncode.sh. Any code in
+# the pending set → exit silently; code always goes through explicit /save and
+# review. Never auto-commits half-finished code.
+#
+# When the gate passes, delegates commit→push→PR→auto-merge to
+# handoff-save-egregore.sh (--kind autosave), and pushes the memory repo.
+#
+# Usage:
+#   session-autosave.sh [--dir <repo-dir>] [--author <name>]
+#                       [--debounce <sec>] [--min-idle <sec>] [--sweep]
+#   --debounce  skip if this dir was autosaved less than <sec> ago (Stop hook)
+#   --min-idle  skip if any dirty file was modified less than <sec> ago
+#               (don't commit prose someone is actively typing)
+#   --sweep     iterate main checkout + .claude/worktrees/* (session start)
+#   (Hook invocations pass nothing; stdin JSON supplies cwd.)
+
+set -uo pipefail
+
+DIR=""
+AUTHOR=""
+DEBOUNCE=0
+MIN_IDLE=0
+SWEEP=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir) DIR="${2:-}"; shift 2 ;;
+    --author) AUTHOR="${2:-}"; shift 2 ;;
+    --debounce) DEBOUNCE="${2:-0}"; shift 2 ;;
+    --min-idle) MIN_IDLE="${2:-0}"; shift 2 ;;
+    --sweep) SWEEP=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+SCRIPT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# --- Sweep mode: rescue abandoned checkouts, then exit -------------------
+if [ "$SWEEP" = "1" ]; then
+  # Let session-start's own git syncs settle before touching the checkout.
+  sleep 15
+  for d in "$SCRIPT_ROOT" "$SCRIPT_ROOT"/.claude/worktrees/*/; do
+    d="${d%/}"
+    [ -d "$d" ] || continue
+    # min-idle protects live sessions in other terminals: never commit files
+    # someone touched in the last 10 minutes. debounce dedupes concurrent
+    # session launches sweeping the same dirs.
+    bash "$0" --dir "$d" --min-idle 600 --debounce 120 >/dev/null 2>&1 || true
+  done
+  exit 0
+fi
+
+# Hook invocations deliver JSON on stdin (cwd = where the session worked).
+if [ -z "$DIR" ] && [ ! -t 0 ]; then
+  HOOK_INPUT=$(cat 2>/dev/null || true)
+  DIR=$(echo "$HOOK_INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+fi
+
+[ -n "$DIR" ] && [ -d "$DIR" ] || DIR="$SCRIPT_ROOT"
+cd "$DIR" 2>/dev/null || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# --- Debounce (per-dir stamp) --------------------------------------------
+# NB: `cmd | cut || fallback` doesn't work — cut succeeds on empty input, so
+# the fallback never fires and every dir collapses to one stamp (macOS has
+# md5, not md5sum). Group the hash commands, then cut.
+DIR_HASH=$( { md5sum <<<"$DIR" 2>/dev/null || md5 -q -s "$DIR" 2>/dev/null || echo default; } | cut -c1-8 )
+STAMP="/tmp/.egregore-autosave-${DIR_HASH}"
+if [ "$DEBOUNCE" -gt 0 ] && [ -f "$STAMP" ]; then
+  LAST=$(stat -f %m "$STAMP" 2>/dev/null || stat -c %Y "$STAMP" 2>/dev/null || echo 0)
+  [ $(( $(date +%s) - LAST )) -lt "$DEBOUNCE" ] && exit 0
+fi
+touch "$STAMP" 2>/dev/null || true
+
+# shellcheck source=bin/lib/noncode.sh
+. "$SCRIPT_ROOT/bin/lib/noncode.sh" 2>/dev/null || exit 0
+
+if [ -z "$AUTHOR" ]; then
+  AUTHOR=$(jq -r '.github_username // .name // empty' "$DIR/.egregore-state.json" 2>/dev/null || true)
+  [ -n "$AUTHOR" ] || AUTHOR=$(jq -r '.github_username // .name // empty' "$SCRIPT_ROOT/.egregore-state.json" 2>/dev/null || true)
+  [ -n "$AUTHOR" ] || AUTHOR=$(git config user.name 2>/dev/null | tr '[:upper:] ' '[:lower:]-' || true)
+  [ -n "$AUTHOR" ] || AUTHOR="egregore"
+fi
+
+# --- Memory repo: markdown by definition, push straight to main ----------
+if git -C "$DIR/memory" rev-parse --git-dir >/dev/null 2>&1; then
+  if [ -n "$(git -C "$DIR/memory" status --porcelain 2>/dev/null)" ]; then
+    git -C "$DIR/memory" add -A >/dev/null 2>&1 || true
+    git -C "$DIR/memory" commit -m "Auto-save: session content" --quiet 2>/dev/null || true
+  fi
+  if [ -n "$(git -C "$DIR/memory" log origin/main..HEAD --oneline 2>/dev/null)" ]; then
+    for _try in 1 2 3; do
+      if git -C "$DIR/memory" pull --rebase origin main --quiet 2>/dev/null \
+         && git -C "$DIR/memory" push origin main --quiet 2>/dev/null; then
+        break
+      fi
+      sleep 1
+    done
+  fi
+fi
+
+# --- Core repo gate: everything pending must be non-coding ---------------
+# -uall expands untracked dirs to individual files: a collapsed "docs/" entry
+# would defeat both the classifier (code nested under a content dir) and the
+# idle guard (directory mtime, not file mtime).
+DIRTY_PATHS=$(git status --porcelain -uall 2>/dev/null | cut -c4- | sed 's/.* -> //' | sed '/^$/d')
+PENDING=$(
+  {
+    printf '%s\n' "$DIRTY_PATHS"
+    git diff origin/develop...HEAD --name-only 2>/dev/null
+  } | sed '/^$/d'
+)
+[ -n "$PENDING" ] || exit 0
+
+BLOCKER=$(printf '%s\n' "$PENDING" | noncode_filter)
+if [ -n "$BLOCKER" ]; then
+  # Code in the pending set — leave it for an explicit /save + review.
+  exit 0
+fi
+
+# --- Idle guard: don't commit files someone is actively editing ----------
+if [ "$MIN_IDLE" -gt 0 ] && [ -n "$DIRTY_PATHS" ]; then
+  NOW=$(date +%s)
+  while IFS= read -r f; do
+    [ -e "$f" ] || continue
+    M=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
+    [ $(( NOW - M )) -lt "$MIN_IDLE" ] && exit 0
+  done <<< "$DIRTY_PATHS"
+fi
+
+ORIG_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+bash "$SCRIPT_ROOT/bin/handoff-save-egregore.sh" "$AUTHOR" \
+  "session content $(date +%Y-%m-%d)" --kind autosave --repo-dir "$DIR" \
+  --branch-suffix "$DIR_HASH" \
+  >/dev/null 2>&1 || true
+
+# Tell the user what just happened. Under the Stop hook this line surfaces in
+# the Claude Code UI; sweep/SessionEnd invocations discard stdout (their trail
+# is the ledger, reported by the next greeting).
+LEDGER="${EGREGORE_AUTOSAVE_LOG:-$HOME/.egregore/autosave.log}"
+LAST=$(grep -F "|autosave|$DIR|" "$LEDGER" 2>/dev/null | tail -1 || true)
+if [ -n "$LAST" ]; then
+  TS=$(echo "$LAST" | cut -d'|' -f1)
+  PR=$(echo "$LAST" | cut -d'|' -f5)
+  RESULT=$(echo "$LAST" | cut -d'|' -f6)
+  NF=$(echo "$LAST" | cut -d'|' -f7)
+  NOW_EPOCH=$(date +%s)
+  TS_EPOCH=$(date -u -j -f %Y-%m-%dT%H:%M:%SZ "$TS" +%s 2>/dev/null || date -u -d "$TS" +%s 2>/dev/null || echo 0)
+  if [ $(( NOW_EPOCH - TS_EPOCH )) -lt 120 ]; then
+    case "$RESULT" in
+      merged) echo "⟲ auto-saved: $NF non-coding file(s) → develop (PR #$PR merged)" ;;
+      open)   echo "⟲ auto-saved: $NF non-coding file(s) → PR #$PR (merge pending)" ;;
+      *)      echo "⟲ auto-saved: $NF non-coding file(s) → branch pushed (PR pending)" ;;
+    esac
+  fi
+fi
+
+# The helper branches off protected branches before committing. If this
+# checkout was on develop/main (e.g. the main checkout during a sweep),
+# restore it so the next session doesn't land on a stray autosave branch.
+case "$ORIG_BRANCH" in
+  develop|main|master)
+    CUR=$(git branch --show-current 2>/dev/null || echo "")
+    if [ "$CUR" != "$ORIG_BRANCH" ]; then
+      git checkout "$ORIG_BRANCH" --quiet 2>/dev/null || true
+      git pull --ff-only origin "$ORIG_BRANCH" --quiet 2>/dev/null || true
+    fi
+    ;;
+esac
+
+exit 0

package/runtime/pi/bin/session-log.sh

@@ -0,0 +1,199 @@
+#!/bin/bash
+# Graceful session-end adapter: write a structured session log to memory/sessions/.
+# Receives runtime-neutral JSON on stdin from Claude Code or Pi.
+# Runs BEFORE transcript-archive.sh (needs obs buffer + worktree intact).
+# Makes sessions visible in local-mode without requiring /handoff or /wrap.
+set -euo pipefail
+
+# Suppress all output — hook scripts must not leak to terminal
+exec >/dev/null 2>&1
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." 2>/dev/null && pwd)" || SCRIPT_DIR=""
+if [ -z "$SCRIPT_DIR" ] || [ ! -d "$SCRIPT_DIR" ]; then
+  SCRIPT_DIR="${CLAUDE_PROJECT_DIR:-}"
+fi
+if [ -z "$SCRIPT_DIR" ] || [ ! -d "$SCRIPT_DIR" ]; then
+  exit 0
+fi
+
+# --- Read hook input from stdin ---
+INPUT=$(cat /dev/stdin 2>/dev/null || echo "{}")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null || true)
+
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+# Sanitize SESSION_ID
+SESSION_ID=$(echo "$SESSION_ID" | tr -cd 'a-zA-Z0-9_-')
+if [ -z "$SESSION_ID" ] || [ ${#SESSION_ID} -gt 128 ]; then
+  exit 0
+fi
+
+# --- Gate: memory must exist ---
+if [ ! -L "$SCRIPT_DIR/memory" ] && [ ! -d "$SCRIPT_DIR/memory" ]; then
+  exit 0
+fi
+
+# --- Read identity ---
+STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
+AUTHOR=""
+DISPLAY_NAME=""
+if [ -f "$STATE_FILE" ]; then
+  AUTHOR=$(jq -r '.github_username // empty' "$STATE_FILE" 2>/dev/null || true)
+  DISPLAY_NAME=$(jq -r '.display_name // empty' "$STATE_FILE" 2>/dev/null || true)
+fi
+AUTHOR=$(echo "$AUTHOR" | tr -cd 'a-zA-Z0-9_-')
+if [ -z "$AUTHOR" ]; then
+  exit 0
+fi
+
+# --- Git metadata ---
+BRANCH=$(git -C "$SCRIPT_DIR" branch --show-current 2>/dev/null || echo "")
+
+# --- Derive topic from branch name ---
+TOPIC=""
+if [ -n "$BRANCH" ] && [ "$BRANCH" != "develop" ] && [ "$BRANCH" != "main" ]; then
+  TOPIC=$(echo "$BRANCH" | sed 's|^dev/[^/]*/||; s|^feature/||; s|^bugfix/||' | tr '-' ' ')
+fi
+[ -z "$TOPIC" ] && TOPIC="session"
+
+# --- Read baseline (written by session-start.sh) ---
+BASELINE_FILE="/tmp/egregore-baseline-${SESSION_ID}.json"
+BASELINE_COMMIT=""
+BASELINE_STARTED=""
+if [ -f "$BASELINE_FILE" ]; then
+  BASELINE_COMMIT=$(jq -r '.commit // empty' "$BASELINE_FILE" 2>/dev/null || true)
+  BASELINE_STARTED=$(jq -r '.started_at // empty' "$BASELINE_FILE" 2>/dev/null || true)
+fi
+
+# --- Extract timestamps from transcript ---
+STARTED_AT=""
+ENDED_AT=""
+if [ -n "$TRANSCRIPT_PATH" ]; then
+  TRANSCRIPT_PATH="${TRANSCRIPT_PATH/#\~/$HOME}"
+  TRANSCRIPT_PATH=$(realpath "$TRANSCRIPT_PATH" 2>/dev/null || echo "")
+  if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+    STARTED_AT=$(head -1 "$TRANSCRIPT_PATH" 2>/dev/null | jq -r '.timestamp // empty' 2>/dev/null || echo "")
+    ENDED_AT=$(tail -1 "$TRANSCRIPT_PATH" 2>/dev/null | jq -r '.timestamp // empty' 2>/dev/null || echo "")
+  fi
+fi
+
+# Use baseline start time if transcript didn't provide one
+[ -z "$STARTED_AT" ] && STARTED_AT="$BASELINE_STARTED"
+# Fallback to now
+[ -z "$ENDED_AT" ] && ENDED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+[ -z "$STARTED_AT" ] && STARTED_AT="$ENDED_AT"
+
+# --- Compute duration ---
+DURATION=""
+DURATION_MIN=0
+if [ -n "$STARTED_AT" ] && [ -n "$ENDED_AT" ]; then
+  S_EPOCH=$(python3 -c "from datetime import datetime; print(int(datetime.fromisoformat('$STARTED_AT'.replace('Z','+00:00')).timestamp()))" 2>/dev/null || echo "0")
+  E_EPOCH=$(python3 -c "from datetime import datetime; print(int(datetime.fromisoformat('$ENDED_AT'.replace('Z','+00:00')).timestamp()))" 2>/dev/null || echo "0")
+  if [ "$S_EPOCH" -gt 0 ] 2>/dev/null && [ "$E_EPOCH" -gt 0 ] 2>/dev/null; then
+    DURATION_MIN=$(( (E_EPOCH - S_EPOCH) / 60 ))
+    if [ "$DURATION_MIN" -lt 1 ] 2>/dev/null; then
+      DURATION="<1min"
+    elif [ "$DURATION_MIN" -lt 60 ] 2>/dev/null; then
+      DURATION="${DURATION_MIN}min"
+    else
+      HOURS=$(( DURATION_MIN / 60 ))
+      MINS=$(( DURATION_MIN % 60 ))
+      if [ "$MINS" -gt 0 ] 2>/dev/null; then
+        DURATION="${HOURS}h ${MINS}min"
+      else
+        DURATION="${HOURS}h"
+      fi
+    fi
+  fi
+fi
+[ -z "$DURATION" ] && DURATION="unknown"
+
+# --- Read obs buffer for files touched ---
+OBS_BUFFER="/tmp/egregore-obs-${SESSION_ID}.jsonl"
+OBS_FILES=""
+OBS_COUNT=0
+if [ -f "$OBS_BUFFER" ] && [ -s "$OBS_BUFFER" ]; then
+  OBS_COUNT=$(wc -l < "$OBS_BUFFER" 2>/dev/null | tr -d ' ')
+  OBS_FILES=$(jq -r '.path // empty' "$OBS_BUFFER" 2>/dev/null | grep -v '^$' | grep -v '^unknown$' | sort -u | head -10 || true)
+fi
+
+# --- Count commits since baseline ---
+COMMIT_COUNT=0
+if [ -n "$BASELINE_COMMIT" ] && git -C "$SCRIPT_DIR" rev-parse "$BASELINE_COMMIT" >/dev/null 2>&1; then
+  COMMIT_COUNT=$(git -C "$SCRIPT_DIR" rev-list "${BASELINE_COMMIT}..HEAD" --count 2>/dev/null || echo "0")
+fi
+
+# --- Empty session guard ---
+# Skip if: duration < 2 min AND no commits AND no obs buffer activity
+if [ "$DURATION_MIN" -lt 2 ] 2>/dev/null && [ "$COMMIT_COUNT" -eq 0 ] 2>/dev/null && [ "$OBS_COUNT" -eq 0 ] 2>/dev/null; then
+  rm -f "$BASELINE_FILE" 2>/dev/null
+  exit 0
+fi
+
+# --- Deduplication: explicit /handoff or /wrap wins over baseline capture ---
+TODAY=$(date +%d)
+MONTH=$(date +%Y-%m)
+if [ -n "$STARTED_AT" ]; then
+  MONTH=$(echo "$STARTED_AT" | grep -oE '^[0-9]{4}-[0-9]{2}' || date +%Y-%m)
+  TODAY=$(echo "$STARTED_AT" | grep -oE '^[0-9]{4}-[0-9]{2}-([0-9]{2})' | tail -c3 | sed 's/^-//' || date +%d)
+fi
+
+AUTHOR_LC=$(echo "$AUTHOR" | tr '[:upper:]' '[:lower:]')
+DISPLAY_LC=$(echo "$DISPLAY_NAME" | tr '[:upper:]' '[:lower:]')
+AUTHOR_PATTERN="-${AUTHOR_LC}-"
+[ -n "$DISPLAY_LC" ] && AUTHOR_PATTERN="${AUTHOR_PATTERN}|-${DISPLAY_LC}-"
+for CAPTURE_DIR in \
+  "$SCRIPT_DIR/memory/handoffs/$MONTH" \
+  "$SCRIPT_DIR/memory/wraps/$MONTH"; do
+  [ -d "$CAPTURE_DIR" ] || continue
+  # Match the canonical handle or display name in today's filename.
+  EXISTING=""
+  for CANDIDATE in "$CAPTURE_DIR/${TODAY}-"*.md; do
+    [ -e "$CANDIDATE" ] || continue
+    CANDIDATE_NAME="$(basename "$CANDIDATE" | tr '[:upper:]' '[:lower:]')"
+    if printf '%s\n' "$CANDIDATE_NAME" | grep -Eq -- "$AUTHOR_PATTERN"; then
+      EXISTING="$CANDIDATE_NAME"
+      break
+    fi
+  done
+  if [ -n "$EXISTING" ]; then
+    rm -f "$BASELINE_FILE" 2>/dev/null
+    exit 0
+  fi
+done
+
+# --- Write through the shared capture engine -----------------------------
+SUMMARY="${DURATION} session on ${TOPIC}; ${COMMIT_COUNT} commit(s), ${OBS_COUNT} observed action(s)."
+{
+  if [ -n "$OBS_FILES" ]; then
+    echo "## Files"
+    echo "$OBS_FILES" | while read -r F; do
+      [ -n "$F" ] && echo "- $F"
+    done
+    echo ""
+  fi
+
+  if [ "$COMMIT_COUNT" -gt 0 ] 2>/dev/null; then
+    echo "## Commits"
+    echo "$COMMIT_COUNT commits on ${BRANCH:-develop}"
+    echo ""
+  fi
+} | bash "$SCRIPT_DIR/bin/capture-run.sh" \
+      --mode baseline \
+      --author "$AUTHOR" \
+      --display-name "$DISPLAY_NAME" \
+      --topic "$TOPIC" \
+      --summary "$SUMMARY" \
+      --session-id "$SESSION_ID" \
+      --branch "${BRANCH:-develop}" \
+      --date "$STARTED_AT" \
+      --duration "$DURATION" \
+      --async-push >/dev/null 2>&1 || true
+
+# --- Clean up baseline ---
+rm -f "$BASELINE_FILE" 2>/dev/null
+
+exit 0

package/runtime/pi/bin/settings.sh

@@ -0,0 +1,274 @@
+#!/bin/bash
+set -euo pipefail
+
+# settings.sh — deterministic config verbs for an Egregore instance.
+#
+# Edits egregore.json atomically. No agent, no network, no session. Idempotent:
+# re-adding an existing item is a no-op success; removing a missing one is too.
+# This is the deterministic core the launcher settings screen (and slash
+# commands) call — the reliability lives here, the surfaces are thin callers.
+#
+# Usage:
+#   settings.sh hosting status|on|off
+#   settings.sh repo list | add <name> [description] | remove <name>
+#   settings.sh admin list | add <github-handle> | remove <github-handle>
+#   settings.sh dump                 # full settings snapshot as JSON (for the launcher)
+#
+# Add --json to a read verb (status/list) for machine-readable output.
+#
+# Exit codes: 0 ok · 1 usage/validation error · 2 config not found.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+_die() { echo "$1" >&2; exit "${2:-1}"; }
+
+_valid_token() {
+  # non-empty, GitHub-handle / repo-name safe charset
+  [ -n "${1:-}" ] && printf '%s' "$1" | grep -qE '^[A-Za-z0-9._-]+$'
+}
+
+_save() {
+  # _save '<jq-filter>' [jq-args...] — apply filter to CONFIG, write atomically.
+  local filter="$1"; shift
+  local tmp
+  tmp="$(mktemp "$CONFIG.XXXXXX")" || _die "cannot create temp file" 1
+  if jq "$@" "$filter" "$CONFIG" > "$tmp" 2>/dev/null && [ -s "$tmp" ]; then
+    mv "$tmp" "$CONFIG"
+  else
+    rm -f "$tmp"
+    _die "failed to update $CONFIG (invalid jq filter or unwritable file)" 1
+  fi
+}
+
+_has_repo() { jq -e --arg n "$1" 'any(.repos[]?; (if type=="object" then .name else . end) == $n)' "$CONFIG" >/dev/null; }
+_has_admin() { jq -e --arg h "$1" 'any(.admins[]?; . == $h)' "$CONFIG" >/dev/null; }
+
+usage() {
+  cat >&2 <<'EOF'
+settings.sh — Egregore instance settings
+
+  settings.sh hosting status|on|off
+  settings.sh repo   list | add <name> [description] | remove <name>
+  settings.sh admin  list | add <github-handle> | remove <github-handle>
+  settings.sh people list | add <github-handle> | remove <github-handle>
+  settings.sh dump                         full snapshot (JSON)
+
+  --json    machine-readable output for status/list
+EOF
+  exit "${1:-1}"
+}
+
+# ── verbs ────────────────────────────────────────────────────────────────
+
+cmd_hosting() {
+  local action="${1:-status}"
+  # NEVER use jq's `// "true"` here: `//` treats an explicit `false` as empty and
+  # would return the default, silently defeating the off-switch. Test `!= false`
+  # so absent/true => enabled, explicit false => disabled. `enabled` is the
+  # resolved boolean string ("true"/"false").
+  local enabled; enabled="$(jq -r '.features.publishing != false' "$CONFIG" 2>/dev/null || echo "true")"
+  case "$action" in
+    status)
+      if [ "$JSON" = 1 ]; then
+        jq -n --argjson on "$enabled" '{domain:"hosting", publishing:$on}'
+      elif [ "$enabled" = "false" ]; then echo "Hosting (egregore.xyz): OFF"
+      else echo "Hosting (egregore.xyz): ON"; fi ;;
+    on)
+      _save '.features.publishing = true'
+      echo "Hosting (egregore.xyz): ON" ;;
+    off)
+      _save '.features.publishing = false'
+      echo "Hosting (egregore.xyz): OFF — artifacts will no longer upload to egregore.xyz" ;;
+    *) _die "usage: settings.sh hosting status|on|off" 1 ;;
+  esac
+}
+
+cmd_repo() {
+  local action="${1:-list}"; shift || true
+  case "$action" in
+    list)
+      if [ "$JSON" = 1 ]; then
+        jq '[.repos[]? | if type=="object" then . else {name:.} end]' "$CONFIG"
+      else
+        jq -r '.repos[]? | if type=="object" then "  " + .name + (if .description then " — " + .description else "" end) else "  " + . end' "$CONFIG"
+      fi ;;
+    add)
+      local name="${1:-}"; shift || true
+      local desc="${*:-}"
+      _valid_token "$name" || _die "usage: settings.sh repo add <name> [description]" 1
+      if _has_repo "$name"; then echo "repo '$name' already managed"; return 0; fi
+      if [ -n "$desc" ]; then
+        _save '.repos = ((.repos // []) + [{name:$n, description:$d}])' --arg n "$name" --arg d "$desc"
+      else
+        _save '.repos = ((.repos // []) + [{name:$n}])' --arg n "$name"
+      fi
+      echo "added repo '$name'"
+      echo "  clone it with: /sync-repos  (or reopen the egregore)" ;;
+    remove)
+      local name="${1:-}"
+      _valid_token "$name" || _die "usage: settings.sh repo remove <name>" 1
+      if ! _has_repo "$name"; then echo "repo '$name' is not managed"; return 0; fi
+      _save '.repos = [.repos[]? | select((if type=="object" then .name else . end) != $n)]' --arg n "$name"
+      echo "removed repo '$name' from config"
+      echo "  note: the local ../$name checkout is left untouched" ;;
+    *) _die "usage: settings.sh repo list|add|remove" 1 ;;
+  esac
+}
+
+cmd_admin() {
+  local action="${1:-list}"; shift || true
+  case "$action" in
+    list)
+      if [ "$JSON" = 1 ]; then jq '{admins:(.admins // [])}' "$CONFIG"
+      else jq -r '.admins[]? | "  " + .' "$CONFIG"; fi ;;
+    add)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh admin add <github-handle>" 1
+      if _has_admin "$h"; then echo "'$h' is already an admin"; return 0; fi
+      _save '.admins = ((.admins // []) + [$h])' --arg h "$h"
+      echo "added admin '$h'" ;;
+    remove)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh admin remove <github-handle>" 1
+      if ! _has_admin "$h"; then echo "'$h' is not an admin"; return 0; fi
+      local count; count="$(jq '(.admins // []) | length' "$CONFIG")"
+      [ "$count" -le 1 ] && _die "refusing to remove the last admin ('$h') — add another admin first" 1
+      _save '.admins = [.admins[]? | select(. != $h)]' --arg h "$h"
+      echo "removed admin '$h'" ;;
+    *) _die "usage: settings.sh admin list|add|remove" 1 ;;
+  esac
+}
+
+# ── people ───────────────────────────────────────────────────────────────
+# People live as files in memory/people/. add/remove manage that directory AND
+# GitHub repo access (the meaningful local grant). Connected-mode extras — the
+# invite link + Telegram (/invite) and Supabase/Neo4j teardown (/delete-user) —
+# are pointed to, not duplicated here.
+
+_people_dir() { echo "$SCRIPT_DIR/memory/people"; }
+
+_people_names() {
+  local pdir; pdir="$(_people_dir)"
+  [ -d "$pdir" ] || return 0
+  ls "$pdir"/*.md 2>/dev/null | while IFS= read -r f; do basename "$f" .md; done \
+    | grep -viE '^(index|readme)$' || true
+}
+
+_people_json() {
+  local names; names="$(_people_names)"
+  if [ -z "$names" ]; then echo '[]'; return; fi
+  printf '%s\n' "$names" | jq -R . | jq -sc 'map(select(length>0))'
+}
+
+_has_person() { [ -f "$(_people_dir)/$1.md" ]; }
+
+# add|remove a GitHub push-collaborator across the instance's repos. Best-effort:
+# no token/org => skip with a note; per-repo failures never abort.
+_people_github() {
+  local user="$1" op="$2" token org repos r
+  token="$(grep '^GITHUB_TOKEN=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d= -f2- || true)"
+  org="$(jq -r '.github_org // empty' "$CONFIG" 2>/dev/null)"
+  if [ -z "$token" ] || [ -z "$org" ]; then
+    echo "  (no GitHub token/org — skipped repo access; run bin/github-auth.sh)" >&2
+    return 0
+  fi
+  repos="$(jq -r '[.repo_name, (.memory_repo // "" | split("/") | last | sub("\\.git$";"")), (.repos[]? | if type=="object" then .name else . end)] | map(select(. != null and . != "")) | unique | .[]' "$CONFIG" 2>/dev/null)"
+  for r in $repos; do
+    if [ "$op" = "add" ]; then
+      curl -s -o /dev/null -X PUT -H "Authorization: Bearer $token" -H "Accept: application/vnd.github+json" \
+        "https://api.github.com/repos/$org/$r/collaborators/$user" -d '{"permission":"push"}' 2>/dev/null || true
+    else
+      curl -s -o /dev/null -X DELETE -H "Authorization: Bearer $token" -H "Accept: application/vnd.github+json" \
+        "https://api.github.com/repos/$org/$r/collaborators/$user" 2>/dev/null || true
+    fi
+  done
+}
+
+# create|remove memory/people/<user>.md, committing ONLY the people dir.
+_people_file() {
+  local user="$1" op="$2" pdir f inviter today
+  pdir="$(_people_dir)"
+  [ -d "$SCRIPT_DIR/memory" ] || { echo "  (no memory dir — skipped person file)" >&2; return 0; }
+  mkdir -p "$pdir"
+  f="$pdir/$user.md"
+  if [ "$op" = "add" ]; then
+    if [ ! -f "$f" ]; then
+      inviter="$(jq -r '.display_name // .github_username // "admin"' "$SCRIPT_DIR/.egregore-state.json" 2>/dev/null || echo admin)"
+      today="$(date -u +%Y-%m-%d)"
+      printf -- '---\nname: %s\nperson_id: github-login:%s\ngithub: %s\ninvited_by: %s\njoined: %s\n---\n' "$user" "$(printf '%s' "$user" | tr '[:upper:]' '[:lower:]')" "$user" "$inviter" "$today" > "$f"
+    fi
+  else
+    rm -f "$f"
+  fi
+  ( cd "$SCRIPT_DIR/memory" 2>/dev/null && git add -A people/ 2>/dev/null \
+      && git commit -q -m "settings: people $op $user" 2>/dev/null \
+      && git push -q 2>/dev/null ) || true
+}
+
+cmd_people() {
+  local action="${1:-list}"; shift || true
+  case "$action" in
+    list)
+      if [ "$JSON" = 1 ]; then _people_json
+      else
+        local names; names="$(_people_names)"
+        if [ -n "$names" ]; then printf '  %s\n' $names; else echo "    (none)"; fi
+      fi ;;
+    add)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh people add <github-handle>" 1
+      if _has_person "$h"; then echo "'$h' is already in people"; return 0; fi
+      _people_github "$h" "add"
+      _people_file "$h" "add"
+      echo "added '$h' (repo access + person file)"
+      [ -n "$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)" ] && echo "  connected org: for the invite link + Telegram, run /invite $h" ;;
+    remove)
+      local h="${1:-}"
+      _valid_token "$h" || _die "usage: settings.sh people remove <github-handle>" 1
+      if ! _has_person "$h"; then echo "'$h' is not in people"; return 0; fi
+      _people_github "$h" "remove"
+      _people_file "$h" "remove"
+      echo "removed '$h' (repo access + person file)"
+      [ -n "$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)" ] && echo "  connected org: for full deprovision (Supabase/Neo4j), run /delete-user $h" ;;
+    *) _die "usage: settings.sh people list|add|remove" 1 ;;
+  esac
+}
+
+cmd_dump() {
+  # Always JSON — the launcher calls this once to render the whole settings screen.
+  local people; people="$(_people_json)"
+  jq --argjson people "$people" '{
+    org: .org_name,
+    slug: .slug,
+    hosting: (.features.publishing != false),
+    repos: [.repos[]? | if type=="object" then . else {name:.} end],
+    admins: (.admins // []),
+    people: $people
+  }' "$CONFIG"
+}
+
+# ── dispatch ─────────────────────────────────────────────────────────────
+
+[ -f "$CONFIG" ] || _die "egregore.json not found at $CONFIG" 2
+
+# Pull out --json (bash 3.2-safe array handling), leave the rest as positionals.
+JSON=0
+_args=()
+for _a in "$@"; do
+  if [ "$_a" = "--json" ]; then JSON=1; else _args+=("$_a"); fi
+done
+set -- "${_args[@]+"${_args[@]}"}"
+
+DOMAIN="${1:-}"; shift || true
+case "$DOMAIN" in
+  hosting) cmd_hosting "$@" ;;
+  repo)    cmd_repo "$@" ;;
+  admin)   cmd_admin "$@" ;;
+  people)  cmd_people "$@" ;;
+  dump)    cmd_dump ;;
+  ""|-h|--help|help) usage 0 ;;
+  *) _die "unknown settings domain: '$DOMAIN' (try: hosting, repo, admin, people, dump)" 1 ;;
+esac