create-egregore 0.19.5 → 0.19.7

package/runtime/codex/bin/lib/metrics.sh

@@ -0,0 +1,374 @@
+# shellcheck shell=bash
+# metrics.sh — Momentum metrics gathering and rendering for startup greetings.
+#
+# Function-only library. Safe to source from bash or zsh.
+
+_metrics_zero_json() {
+  printf '%s\n' '{"source":"local","sessions":{"buckets":[0,0,0,0,0],"week":0,"prev":0,"all":0},"commits":{"buckets":[0,0,0,0,0],"week":0,"prev":0,"authors":0,"all":0},"handoffs":{"buckets":[0,0,0,0,0],"week":0,"prev":0,"avg_resolution_days":null,"all":0},"knowledge":{"buckets":[0,0,0,0,0],"week":0,"prev":0,"all":0},"members":{"active":0,"total":0}}'
+}
+
+_num() {
+  awk '{n=$1+0; if (n < 0) n=0; printf "%d\n", n}' 2>/dev/null <<EOF
+$1
+EOF
+}
+
+_num_float() {
+  awk '{n=$1+0; if (n < 0) n=0; printf "%.1f\n", n}' 2>/dev/null <<EOF
+$1
+EOF
+}
+
+_normalize_buckets() {
+  set -- $(printf '%s' "$1")
+  printf '%d %d %d %d %d\n' "$(_num "${1:-0}")" "$(_num "${2:-0}")" "$(_num "${3:-0}")" "$(_num "${4:-0}")" "$(_num "${5:-0}")"
+}
+
+_buckets_json() {
+  set -- $(printf '%s' "$(_normalize_buckets "$1")")
+  jq -n --argjson a "$(_num "${1:-0}")" --argjson b "$(_num "${2:-0}")" \
+    --argjson c "$(_num "${3:-0}")" --argjson d "$(_num "${4:-0}")" \
+    --argjson e "$(_num "${5:-0}")" '[$a,$b,$c,$d,$e]' 2>/dev/null || echo '[0,0,0,0,0]'
+}
+
+_bucket_week() {
+  set -- $(printf '%s' "$(_normalize_buckets "$1")")
+  _num "${5:-0}"
+}
+
+_bucket_prev() {
+  set -- $(printf '%s' "$(_normalize_buckets "$1")")
+  _num "${4:-0}"
+}
+
+_spark() {
+  local values max out v idx glyph
+  values="${1:-0 0 0 0 0}"
+  max=0
+  set -- $(printf '%s' "$values")
+  [ "$#" -eq 0 ] && set -- 0 0 0 0 0
+  for v in "$@"; do
+    v=$(_num "$v")
+    [ "$v" -gt "$max" ] 2>/dev/null && max="$v"
+  done
+  out=""
+  for v in "$@"; do
+    v=$(_num "$v")
+    if [ "$max" -le 0 ] 2>/dev/null; then
+      idx=0
+    else
+      idx=$(( (v * 7) / max ))
+    fi
+    # Select glyphs explicitly: substring slicing can split UTF-8 characters
+    # under Bash 3.2 or a C locale.
+    case "$idx" in
+      0) glyph="▁" ;;
+      1) glyph="▂" ;;
+      2) glyph="▃" ;;
+      3) glyph="▄" ;;
+      4) glyph="▅" ;;
+      5) glyph="▆" ;;
+      6) glyph="▇" ;;
+      *) glyph="█" ;;
+    esac
+    out="${out}${glyph}"
+  done
+  printf '%s\n' "$out"
+}
+
+_pct_delta() {
+  local cur prev pct
+  cur=$(_num "${1:-0}")
+  prev=$(_num "${2:-0}")
+  [ "$prev" -le 0 ] 2>/dev/null && return 0
+  pct=$(( ((cur - prev) * 100) / prev ))
+  if [ "$pct" -gt 0 ] 2>/dev/null; then
+    printf '↑ %d%%\n' "$pct"
+  elif [ "$pct" -lt 0 ] 2>/dev/null; then
+    printf '↓ %d%%\n' "$(( -pct ))"
+  else
+    printf '→ 0%%\n'
+  fi
+}
+
+_commafy() {
+  awk '
+    function comma(s, out, sign) {
+      s = int(s + 0)
+      if (s < 0) { sign = "-"; s = -s } else { sign = "" }
+      s = sprintf("%d", s)
+      out = ""
+      while (length(s) > 3) {
+        out = "," substr(s, length(s) - 2, 3) out
+        s = substr(s, 1, length(s) - 3)
+      }
+      return sign s out
+    }
+    { print comma($1) }
+  ' 2>/dev/null <<EOF
+${1:-0}
+EOF
+}
+
+_git_added_buckets() {
+  local repo now paths
+  repo="$1"
+  shift
+  now=$(date +%s)
+  if [ -d "$repo" ] || [ -f "$repo" ]; then
+    git -C "$repo" log --diff-filter=A --since="35 days ago" --format='%ct' -- "$@" 2>/dev/null | \
+      awk -v now="$now" '
+        BEGIN { for (i=0;i<5;i++) b[i]=0 }
+        /^[0-9]+$/ {
+          days = int((now - $1) / 86400)
+          idx = 4 - int(days / 7)
+          if (idx >= 0 && idx < 5) b[idx]++
+        }
+        END { printf "%d %d %d %d %d\n", b[0], b[1], b[2], b[3], b[4] }
+      ' 2>/dev/null || echo "0 0 0 0 0"
+  else
+    echo "0 0 0 0 0"
+  fi
+}
+
+_find_count_md() {
+  find -L "$@" -name '*.md' ! -name 'index*' 2>/dev/null | wc -l | awk '{print $1+0}' 2>/dev/null || echo 0
+}
+
+_metrics_gather() {
+  local _root _mem _scratch _API_URL _API_KEY _connected
+  _root="${SCRIPT_DIR:-$PWD}"
+  _mem="$_root/memory"
+  _scratch=$(mktemp -d 2>/dev/null || mktemp -d -t egregore-metrics)
+  _API_URL=$(jq -r '.api_url // empty' "$_root/egregore.json" 2>/dev/null || echo "")
+  _API_KEY=$(grep '^EGREGORE_API_KEY=' "${ENV_FILE:-$_root/.env}" 2>/dev/null | cut -d'=' -f2- || true)
+  _connected=false
+  [ -n "$_API_URL" ] && [ -n "$_API_KEY" ] && _connected=true
+
+  (
+    if [ "$_connected" = true ]; then
+      raw=$(bash "$_root/bin/graph.sh" query "MATCH (s:Session) WHERE date(s.date) >= date() - duration('P35D')
+OPTIONAL MATCH (s)-[:BY]->(p:Person)
+WITH duration.inDays(date(s.date), date()).days / 7 AS weeksAgo,
+     count(s) AS sessions, count(DISTINCT p) AS people
+RETURN weeksAgo, sessions, people ORDER BY weeksAgo" 2>/dev/null || echo "")
+      printf '%s' "$raw" | jq -r '
+        (.values // []) as $v
+        | if ($v|length) == 0 then empty else
+          reduce $v[] as $r ({b:[0,0,0,0,0], a:0, ok:0};
+            ($r[0] // 99 | tonumber? // 99) as $w
+            | if $w >= 0 and $w <= 4 then
+                .b[4 - $w] = (($r[1] // 0 | tonumber? // 0) | floor)
+                | .ok = 1
+                | if $w == 0 then .a = (($r[2] // 0 | tonumber? // 0) | floor) else . end
+              else . end)
+          | "\(.b|join(" "))|\(.a)|\(.ok)"
+          end
+      ' 2>/dev/null || echo "0 0 0 0 0|0|0"
+    else
+      echo "0 0 0 0 0|0|0"
+    fi
+  ) > "$_scratch/graph_sessions" 2>/dev/null &
+
+  (
+    if [ "$_connected" = true ]; then
+      raw=$(bash "$_root/bin/graph.sh" query "MATCH (s:Session) WITH count(s) AS totalSessions MATCH (p:Person)-[:MEMBER_OF]->(:Org) RETURN totalSessions, count(DISTINCT p) AS members" 2>/dev/null || echo "")
+      total=$(printf '%s' "$raw" | jq -r '.values[0][0] // 0' 2>/dev/null || echo 0)
+      members=$(printf '%s' "$raw" | jq -r '.values[0][1] // 0' 2>/dev/null || echo 0)
+      if [ "$(_num "$members")" -eq 0 ] 2>/dev/null; then
+        raw2=$(bash "$_root/bin/graph.sh" query "MATCH (p:Person) RETURN count(p)" 2>/dev/null || echo "")
+        members=$(printf '%s' "$raw2" | jq -r '.values[0][0] // 0' 2>/dev/null || echo 0)
+      fi
+      printf '%s|%s\n' "$(_num "$total")" "$(_num "$members")"
+    else
+      echo "0|0"
+    fi
+  ) > "$_scratch/graph_totals" 2>/dev/null &
+
+  (
+    if [ "$_connected" = true ]; then
+      raw=$(bash "$_root/bin/graph.sh" query "MATCH (s:Session)-[:HANDED_TO]->(:Person)
+WHERE s.handoffStatus = 'done' AND date(s.date) >= date() - duration('P30D')
+  AND s.handoffReadDate IS NOT NULL
+WITH duration.inDays(date(s.date), date(s.handoffReadDate)).days AS d
+RETURN avg(d) AS avgDays, count(*) AS n" 2>/dev/null || echo "")
+      avg=$(printf '%s' "$raw" | jq -r '.values[0][0] // empty' 2>/dev/null || echo "")
+      n=$(printf '%s' "$raw" | jq -r '.values[0][1] // 0' 2>/dev/null || echo 0)
+      if [ "$(_num "$n")" -gt 0 ] 2>/dev/null && [ -n "$avg" ]; then _num_float "$avg"; else echo ""; fi
+    else
+      echo ""
+    fi
+  ) > "$_scratch/handoff_resolution" 2>/dev/null &
+
+  (
+    buckets=$(_git_added_buckets "$_mem" sessions wraps)
+    all=$(_find_count_md "$_root/memory/sessions" "$_root/memory/wraps")
+    printf '%s|%s\n' "$buckets" "$all"
+  ) > "$_scratch/local_sessions" 2>/dev/null &
+
+  (
+    now=$(date +%s)
+    if [ -d "$_mem" ] || [ -f "$_mem" ]; then
+      git -C "$_mem" log --since="35 days ago" --format='%ct|%ae' 2>/dev/null | \
+        awk -F'|' -v now="$now" '
+          BEGIN { for (i=0;i<5;i++) b[i]=0 }
+          {
+            days = int((now - $1) / 86400)
+            idx = 4 - int(days / 7)
+            if (idx >= 0 && idx < 5) {
+              b[idx]++
+              if (idx == 4 && $2 != "") a[$2]=1
+            }
+          }
+          END {
+            n=0; for (k in a) n++
+            printf "%d %d %d %d %d|%d\n", b[0], b[1], b[2], b[3], b[4], n
+          }
+        ' 2>/dev/null || echo "0 0 0 0 0|0"
+    else
+      echo "0 0 0 0 0|0"
+    fi
+  ) > "$_scratch/commits" 2>/dev/null &
+
+  (
+    if [ -d "$_mem" ] || [ -f "$_mem" ]; then git -C "$_mem" rev-list --count HEAD 2>/dev/null || echo 0; else echo 0; fi
+  ) > "$_scratch/commits_all" 2>/dev/null &
+
+  (
+    buckets=$(_git_added_buckets "$_mem" handoffs)
+    all=$(_find_count_md "$_root/memory/handoffs")
+    printf '%s|%s\n' "$buckets" "$all"
+  ) > "$_scratch/handoffs" 2>/dev/null &
+
+  (
+    buckets=$(_git_added_buckets "$_mem" knowledge/decisions knowledge/findings knowledge/patterns)
+    all=$(_find_count_md "$_root/memory/knowledge/decisions" "$_root/memory/knowledge/findings" "$_root/memory/knowledge/patterns")
+    printf '%s|%s\n' "$buckets" "$all"
+  ) > "$_scratch/knowledge" 2>/dev/null &
+
+  (
+    _find_count_md "$_root/memory/people"
+  ) > "$_scratch/members_total_local" 2>/dev/null &
+
+  wait
+
+  gs=$(cat "$_scratch/graph_sessions" 2>/dev/null || echo "0 0 0 0 0|0|0")
+  gt=$(cat "$_scratch/graph_totals" 2>/dev/null || echo "0|0")
+  lsess=$(cat "$_scratch/local_sessions" 2>/dev/null || echo "0 0 0 0 0|0")
+  commits=$(cat "$_scratch/commits" 2>/dev/null || echo "0 0 0 0 0|0")
+  handoffs=$(cat "$_scratch/handoffs" 2>/dev/null || echo "0 0 0 0 0|0")
+  knowledge=$(cat "$_scratch/knowledge" 2>/dev/null || echo "0 0 0 0 0|0")
+
+  graph_valid=$(_num "$(printf '%s' "$gs" | awk -F'|' '{print $3}')")
+  if [ "$graph_valid" -gt 0 ] 2>/dev/null; then
+    source_name="graph"
+    session_buckets=$(_normalize_buckets "$(printf '%s' "$gs" | awk -F'|' '{print $1}')")
+    session_all=$(_num "$(printf '%s' "$gt" | awk -F'|' '{print $1}')")
+    members_active=$(_num "$(printf '%s' "$gs" | awk -F'|' '{print $2}')")
+    members_total=$(_num "$(printf '%s' "$gt" | awk -F'|' '{print $2}')")
+    if [ "$session_all" -le 0 ] 2>/dev/null; then
+      session_all=$(_num "$(printf '%s' "$lsess" | awk -F'|' '{print $2}')")
+    fi
+    if [ "$members_total" -le 0 ] 2>/dev/null; then
+      members_total=$(_num "$(cat "$_scratch/members_total_local" 2>/dev/null || echo 0)")
+    fi
+  else
+    source_name="local"
+    session_buckets=$(_normalize_buckets "$(printf '%s' "$lsess" | awk -F'|' '{print $1}')")
+    session_all=$(_num "$(printf '%s' "$lsess" | awk -F'|' '{print $2}')")
+    members_active=$(_num "$(printf '%s' "$commits" | awk -F'|' '{print $2}')")
+    members_total=$(_num "$(cat "$_scratch/members_total_local" 2>/dev/null || echo 0)")
+  fi
+
+  commit_buckets=$(_normalize_buckets "$(printf '%s' "$commits" | awk -F'|' '{print $1}')")
+  handoff_buckets=$(_normalize_buckets "$(printf '%s' "$handoffs" | awk -F'|' '{print $1}')")
+  knowledge_buckets=$(_normalize_buckets "$(printf '%s' "$knowledge" | awk -F'|' '{print $1}')")
+  avg_res=$(cat "$_scratch/handoff_resolution" 2>/dev/null || echo "")
+
+  session_buckets_json=$(_buckets_json "$session_buckets")
+  commit_buckets_json=$(_buckets_json "$commit_buckets")
+  handoff_buckets_json=$(_buckets_json "$handoff_buckets")
+  knowledge_buckets_json=$(_buckets_json "$knowledge_buckets")
+
+  if [ -n "$avg_res" ]; then
+    jq -n --arg source "$source_name" \
+      --argjson sb "$session_buckets_json" --argjson sw "$(_bucket_week "$session_buckets")" --argjson sp "$(_bucket_prev "$session_buckets")" --argjson sall "$session_all" \
+      --argjson cb "$commit_buckets_json" --argjson cw "$(_bucket_week "$commit_buckets")" --argjson cp "$(_bucket_prev "$commit_buckets")" --argjson ca "$(_num "$(printf '%s' "$commits" | awk -F'|' '{print $2}')")" --argjson call "$(_num "$(cat "$_scratch/commits_all" 2>/dev/null || echo 0)")" \
+      --argjson hb "$handoff_buckets_json" --argjson hw "$(_bucket_week "$handoff_buckets")" --argjson hp "$(_bucket_prev "$handoff_buckets")" --argjson havg "$avg_res" --argjson hall "$(_num "$(printf '%s' "$handoffs" | awk -F'|' '{print $2}')")" \
+      --argjson kb "$knowledge_buckets_json" --argjson kw "$(_bucket_week "$knowledge_buckets")" --argjson kp "$(_bucket_prev "$knowledge_buckets")" --argjson kall "$(_num "$(printf '%s' "$knowledge" | awk -F'|' '{print $2}')")" \
+      --argjson ma "$members_active" --argjson mt "$members_total" \
+      '{source:$source,sessions:{buckets:$sb,week:$sw,prev:$sp,all:$sall},commits:{buckets:$cb,week:$cw,prev:$cp,authors:$ca,all:$call},handoffs:{buckets:$hb,week:$hw,prev:$hp,avg_resolution_days:$havg,all:$hall},knowledge:{buckets:$kb,week:$kw,prev:$kp,all:$kall},members:{active:$ma,total:$mt}}' 2>/dev/null || _metrics_zero_json
+  else
+    jq -n --arg source "$source_name" \
+      --argjson sb "$session_buckets_json" --argjson sw "$(_bucket_week "$session_buckets")" --argjson sp "$(_bucket_prev "$session_buckets")" --argjson sall "$session_all" \
+      --argjson cb "$commit_buckets_json" --argjson cw "$(_bucket_week "$commit_buckets")" --argjson cp "$(_bucket_prev "$commit_buckets")" --argjson ca "$(_num "$(printf '%s' "$commits" | awk -F'|' '{print $2}')")" --argjson call "$(_num "$(cat "$_scratch/commits_all" 2>/dev/null || echo 0)")" \
+      --argjson hb "$handoff_buckets_json" --argjson hw "$(_bucket_week "$handoff_buckets")" --argjson hp "$(_bucket_prev "$handoff_buckets")" --argjson hall "$(_num "$(printf '%s' "$handoffs" | awk -F'|' '{print $2}')")" \
+      --argjson kb "$knowledge_buckets_json" --argjson kw "$(_bucket_week "$knowledge_buckets")" --argjson kp "$(_bucket_prev "$knowledge_buckets")" --argjson kall "$(_num "$(printf '%s' "$knowledge" | awk -F'|' '{print $2}')")" \
+      --argjson ma "$members_active" --argjson mt "$members_total" \
+      '{source:$source,sessions:{buckets:$sb,week:$sw,prev:$sp,all:$sall},commits:{buckets:$cb,week:$cw,prev:$cp,authors:$ca,all:$call},handoffs:{buckets:$hb,week:$hw,prev:$hp,avg_resolution_days:null,all:$hall},knowledge:{buckets:$kb,week:$kw,prev:$kp,all:$kall},members:{active:$ma,total:$mt}}' 2>/dev/null || _metrics_zero_json
+  fi
+  rm -rf "$_scratch" 2>/dev/null || true
+}
+
+_metrics_read() {
+  local file filter fallback
+  file="${CTX_DIR:-}/metrics"
+  filter="$1"
+  fallback="$2"
+  if [ -f "$file" ]; then
+    jq -r "$filter" "$file" 2>/dev/null || echo "$fallback"
+  else
+    echo "$fallback"
+  fi
+}
+
+_render_momentum_board() {
+  local separator line_width header_left header_right pad
+  local sb sw sp sall cb cw ca call hb hw havg hall kb kw kall active total
+  local sdelta sann cann hann kann know_week
+  separator="${SEPARATOR:-  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄}"
+  line_width="${LINE_WIDTH:-67}"
+
+  sb=$(_metrics_read '(.sessions.buckets // [0,0,0,0,0]) | .[0:5] | map(. // 0) | join(" ")' "0 0 0 0 0")
+  sw=$(_num "$(_metrics_read '.sessions.week // 0' "0")")
+  sp=$(_num "$(_metrics_read '.sessions.prev // 0' "0")")
+  sall=$(_num "$(_metrics_read '.sessions.all // 0' "0")")
+  cb=$(_metrics_read '(.commits.buckets // [0,0,0,0,0]) | .[0:5] | map(. // 0) | join(" ")' "0 0 0 0 0")
+  cw=$(_num "$(_metrics_read '.commits.week // 0' "0")")
+  ca=$(_num "$(_metrics_read '.commits.authors // 0' "0")")
+  call=$(_num "$(_metrics_read '.commits.all // 0' "0")")
+  hb=$(_metrics_read '(.handoffs.buckets // [0,0,0,0,0]) | .[0:5] | map(. // 0) | join(" ")' "0 0 0 0 0")
+  hw=$(_num "$(_metrics_read '.handoffs.week // 0' "0")")
+  havg=$(_metrics_read '.handoffs.avg_resolution_days // empty' "")
+  hall=$(_num "$(_metrics_read '.handoffs.all // 0' "0")")
+  kb=$(_metrics_read '(.knowledge.buckets // [0,0,0,0,0]) | .[0:5] | map(. // 0) | join(" ")' "0 0 0 0 0")
+  kw=$(_num "$(_metrics_read '.knowledge.week // 0' "0")")
+  kall=$(_num "$(_metrics_read '.knowledge.all // 0' "0")")
+  active=$(_num "$(_metrics_read '.members.active // 0' "0")")
+  total=$(_num "$(_metrics_read '.members.total // 0' "0")")
+
+  header_left="  ◦ momentum · this week"
+  header_right="${active} of ${total} active"
+  pad=$((line_width - ${#header_left} - ${#header_right}))
+  [ "$pad" -lt 1 ] && pad=1
+  printf "%s%*s%s\n" "$header_left" "$pad" "" "$header_right"
+
+  sdelta=$(_pct_delta "$sw" "$sp")
+  sann=""
+  [ -n "$sdelta" ] && sann="${sdelta} vs last week"
+  cann=""
+  if [ "$ca" -gt 0 ] 2>/dev/null; then
+    if [ "$ca" -eq 1 ] 2>/dev/null; then cann="1 author"; else cann="${ca} authors"; fi
+  fi
+  hann=""
+  if [ -n "$havg" ]; then hann="$(_num_float "$havg")d avg resolution"; fi
+  kann="$(_commafy "$kall") artifacts total"
+  know_week="+${kw}"
+
+  printf "  %-11s%5s   5-week %s   %s\n\n" "sessions" "$sw" "$(_spark "$sb")" "$sann"
+  printf "  %-11s%5s   5-week %s   %s\n\n" "commits" "$cw" "$(_spark "$cb")" "$cann"
+  printf "  %-11s%5s   5-week %s   %s\n\n" "handoffs" "$hw" "$(_spark "$hb")" "$hann"
+  printf "  %-11s%5s   5-week %s   %s\n" "knowledge" "$know_week" "$(_spark "$kb")" "$kann"
+  echo "$separator"
+  printf "  %s sessions · %s commits · %s handoffs all-time\n" "$(_commafy "$sall")" "$(_commafy "$call")" "$(_commafy "$hall")"
+}

package/runtime/codex/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/codex/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\ngithub: %s\ninvited_by: %s\njoined: %s\n---\n' "$user" "$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