youmd 0.7.1 → 0.8.0

package/scripts/env-vault/backup.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
-# env-vault/backup.sh — backs up all .env.local files under CODE_2025 into an
-# encrypted vault. NEVER prints, echoes, logs, or writes any secret VALUE.
-# Only variable NAMES and counts appear in plaintext output.
+# env-vault/backup.sh — backs up all .env.local files under CODE_2025 AND a
+# fixed set of agent-auth secret files into an encrypted vault. NEVER prints,
+# echoes, logs, or writes any secret VALUE. Only variable NAMES, counts, and
+# file paths appear in plaintext output.
 #
 # Usage: bash backup.sh [--root <search-root>] [--out <output-dir>]
 # Defaults:
@@ -14,6 +15,16 @@ set -euo pipefail
 SEARCH_ROOT="${ENV_VAULT_ROOT:-/Users/houstongolden/Desktop/CODE_2025}"
 OUTPUT_DIR="${ENV_VAULT_OUT:-/Users/houstongolden/Desktop/CODE_2025/youmd/.env-vault}"
 
+# ── agent-auth secret files ────────────────────────────────────────────────────
+# Absolute paths to hard agent-auth secrets that must travel with the vault.
+# Each entry is archived as agent-auth/<stable-name> inside the tar.
+# To add more: append to this array. Format: "absolute-path:stable-archive-name"
+AGENT_SECRET_FILES=(
+  "${HOME}/.codex/auth.json:codex-auth.json"
+  "${HOME}/.cursor/mcp.json:cursor-mcp.json"
+  "${HOME}/.claude.json:claude.json"
+)
+
 # ── parse flags ────────────────────────────────────────────────────────────────
 while [[ $# -gt 0 ]]; do
   case $1 in
@@ -94,6 +105,38 @@ for ENV_FILE in "${ENV_FILES[@]}"; do
     >> "${MANIFEST_PATH}"
 done
 
+# ── stage agent-auth secret files ─────────────────────────────────────────────
+# Each entry in AGENT_SECRET_FILES has format "absolute-path:stable-archive-name".
+# Files are stored under agent-auth/<stable-name> inside the archive.
+# Only the path and byte-size appear in the manifest — never the contents.
+AGENT_AUTH_STAGING="${STAGING_DIR}/agent-auth"
+mkdir -p "${AGENT_AUTH_STAGING}"
+AGENT_AUTH_COUNT=0
+
+echo "" >> "${MANIFEST_PATH}"
+echo "agent-auth files:" >> "${MANIFEST_PATH}"
+
+for ENTRY in "${AGENT_SECRET_FILES[@]}"; do
+  SRC_PATH="${ENTRY%%:*}"
+  ARCHIVE_NAME="${ENTRY##*:}"
+
+  if [[ -f "${SRC_PATH}" ]]; then
+    cp "${SRC_PATH}" "${AGENT_AUTH_STAGING}/${ARCHIVE_NAME}"
+    FILE_BYTES=$(wc -c < "${SRC_PATH}" | tr -d ' ')
+    echo "  agent-auth/${ARCHIVE_NAME} (${SRC_PATH}): ${FILE_BYTES} bytes" \
+      >> "${MANIFEST_PATH}"
+    echo "  Staged agent-auth: ${SRC_PATH} → agent-auth/${ARCHIVE_NAME}"
+    (( AGENT_AUTH_COUNT++ )) || true
+  else
+    echo "  agent-auth/${ARCHIVE_NAME} (${SRC_PATH}): NOT FOUND — skipped" \
+      >> "${MANIFEST_PATH}"
+    echo "  Skipped (not found): ${SRC_PATH}"
+  fi
+done
+
+echo ""
+echo "Staged ${AGENT_AUTH_COUNT} agent-auth file(s)."
+
 echo "" >> "${MANIFEST_PATH}"
 echo "SECURITY: The encrypted archive is safe to transport. Keep the passphrase private." \
   >> "${MANIFEST_PATH}"

package/scripts/env-vault/restore.sh

@@ -1,15 +1,31 @@
 #!/usr/bin/env bash
-# env-vault/restore.sh — restores .env.local files from an encrypted vault
-# created by backup.sh. NEVER prints, echoes, or logs any secret VALUES.
-# Only prints which file paths were restored or skipped.
+# env-vault/restore.sh — restores .env.local files AND agent-auth secrets from
+# an encrypted vault created by backup.sh. NEVER prints, echoes, or logs any
+# secret VALUES. Only prints which file paths were restored or skipped.
 #
 # Usage: bash restore.sh [--force] [--root <target-root>] <vault-file>
 #   vault-file: path to env-vault-*.tar.age / .tar.gpg / .tar.enc
-#   --force:    overwrite existing .env.local files without backing them up
-#   --root:     destination root (default: /Users/houstongolden/Desktop/CODE_2025)
+#   --force:    overwrite existing files without backing them up
+#   --root:     destination root for .env.local files
+#               (default: /Users/houstongolden/Desktop/CODE_2025)
+#
+# agent-auth restore map (archive name → absolute home path):
+#   agent-auth/codex-auth.json  → ~/.codex/auth.json
+#   agent-auth/cursor-mcp.json  → ~/.cursor/mcp.json
+#   agent-auth/claude.json      → ~/.claude.json
 
 set -euo pipefail
 
+# ── agent-auth restore map ─────────────────────────────────────────────────────
+# Maps archive name (inside agent-auth/) to its absolute home destination.
+# Format: "archive-name:absolute-destination-path"
+# Must stay in sync with AGENT_SECRET_FILES in backup.sh.
+AGENT_AUTH_MAP=(
+  "codex-auth.json:${HOME}/.codex/auth.json"
+  "cursor-mcp.json:${HOME}/.cursor/mcp.json"
+  "claude.json:${HOME}/.claude.json"
+)
+
 # ── defaults ──────────────────────────────────────────────────────────────────
 TARGET_ROOT="${ENV_VAULT_RESTORE_ROOT:-/Users/houstongolden/Desktop/CODE_2025}"
 FORCE=false
@@ -139,11 +155,61 @@ while IFS= read -r -d '' ENV_FILE; do
   fi
 done < <(find "${EXTRACT_DIR}" -name ".env.local" -print0)
 
+# ── restore agent-auth files ───────────────────────────────────────────────────
+AGENT_RESTORED=0
+AGENT_SKIPPED=0
+AGENT_BACKED_UP=0
+
+AGENT_AUTH_SRC="${EXTRACT_DIR}/agent-auth"
+
+if [[ -d "${AGENT_AUTH_SRC}" ]]; then
+  echo "Restoring agent-auth files…"
+  for ENTRY in "${AGENT_AUTH_MAP[@]}"; do
+    ARCHIVE_NAME="${ENTRY%%:*}"
+    DEST_PATH="${ENTRY##*:}"
+    SRC_FILE="${AGENT_AUTH_SRC}/${ARCHIVE_NAME}"
+
+    if [[ ! -f "${SRC_FILE}" ]]; then
+      echo "  SKIPPED (not in vault): agent-auth/${ARCHIVE_NAME}"
+      (( AGENT_SKIPPED++ )) || true
+      continue
+    fi
+
+    DEST_DIR="$(dirname "${DEST_PATH}")"
+    mkdir -p "${DEST_DIR}"
+
+    if [[ -f "${DEST_PATH}" ]]; then
+      if [[ "${FORCE}" == "true" ]]; then
+        cp "${SRC_FILE}" "${DEST_PATH}"
+        echo "  RESTORED (overwrite): ${DEST_PATH}"
+        (( AGENT_RESTORED++ )) || true
+      else
+        TS="$(date -u +%Y%m%dT%H%M%SZ)"
+        BAK="${DEST_PATH}.bak.${TS}"
+        cp "${DEST_PATH}" "${BAK}"
+        cp "${SRC_FILE}" "${DEST_PATH}"
+        echo "  RESTORED (backed up old → $(basename "${BAK}")): ${DEST_PATH}"
+        (( AGENT_RESTORED++ )) || true
+        (( AGENT_BACKED_UP++ )) || true
+      fi
+    else
+      cp "${SRC_FILE}" "${DEST_PATH}"
+      echo "  RESTORED (new): ${DEST_PATH}"
+      (( AGENT_RESTORED++ )) || true
+    fi
+  done
+  echo ""
+else
+  echo "No agent-auth/ directory in vault — skipping agent-auth restore."
+  echo ""
+fi
+
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "  Restore summary"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "  Restored: ${RESTORED}  |  Skipped: ${SKIPPED}  |  Old files backed up: ${BACKED_UP}"
+echo "  .env.local  — Restored: ${RESTORED}  |  Skipped: ${SKIPPED}  |  Old files backed up: ${BACKED_UP}"
+echo "  agent-auth  — Restored: ${AGENT_RESTORED}  |  Skipped: ${AGENT_SKIPPED}  |  Old files backed up: ${AGENT_BACKED_UP}"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
-echo "Secrets are now in place. Do not print or share .env.local files."
+echo "Secrets are now in place. Do not print or share secret files."

package/scripts/skillstack-sync/bootstrap-new-mac.sh

@@ -101,14 +101,29 @@ for skill in ${LOOSE_SKILLS}; do
 done
 
 # ---------------------------------------------------------------------------
-step "5. Reminder: restore secrets"
+step "5. Restore agent config from agent-shared"
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RESTORE_SCRIPT="${SCRIPT_DIR}/restore-agent-config.sh"
+
+if [ -f "${RESTORE_SCRIPT}" ]; then
+  info "Running restore-agent-config.sh (backs up existing files, safe to re-run)..."
+  bash "${RESTORE_SCRIPT}"
+  info "Agent config restored."
+else
+  warn "restore-agent-config.sh not found at ${RESTORE_SCRIPT} — skipping agent config restore."
+  warn "You can run it manually later once youmd is fully installed:"
+  warn "  bash ${RESTORE_SCRIPT}"
+fi
+
+# ---------------------------------------------------------------------------
+step "6. Reminder: restore secrets"
 # ---------------------------------------------------------------------------
 echo ""
 echo "  !! IMPORTANT: Secrets are NOT in git. Restore them separately:"
 echo ""
-echo "     If you use the env-vault (~/Desktop/CODE_2025/youmd/cli/scripts/env-vault/):"
+echo "     If you use the env-vault:"
 echo "       youmd env restore <vault-file>   # CLI wrapper (preferred)"
-echo "       bash ~/Desktop/CODE_2025/youmd/cli/scripts/env-vault/restore.sh <vault-file>"
 echo ""
 echo "     Secrets to restore (set in your shell profile or .env files):"
 echo "       OPENROUTER_API_KEY"
@@ -119,7 +134,7 @@ echo "       ANTHROPIC_API_KEY"
 echo ""
 
 # ---------------------------------------------------------------------------
-step "6. Next steps"
+step "7. Next steps"
 # ---------------------------------------------------------------------------
 echo ""
 echo "  Bootstrap complete. To activate the auto-sync daemons, run:"
@@ -127,7 +142,6 @@ echo ""
 echo "    youmd stack daemon install        # preferred (CLI-native)"
 echo ""
 echo "  Or run the raw script directly:"
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 echo "    bash ${SCRIPT_DIR}/install-daemons.sh"
 echo ""
 echo "  To do a manual sync now:"

package/scripts/skillstack-sync/capture-agent-config.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# capture-agent-config.sh — snapshot NON-SECRET agent config into ~/.agent-shared/
+#
+# This captures the agent-behavior config that isn't already in a synced repo —
+# Claude/Codex/Warp settings, slash commands, plugin list, the orphaned
+# ~/.agents skills, and the launchd/cron automations — into the agent-shared
+# repo so they travel across machines. The skillstack-sync daemon then commits +
+# pushes agent-shared, and `youmd machine setup`/restore applies them on a new Mac.
+#
+# SECRETS NEVER GO HERE. agent-shared is a git repo. Live secrets (codex
+# auth.json, cursor mcp.json, ~/.claude.json BAMF token, .env.local) travel via
+# the ENCRYPTED env-vault instead. This script captures only files confirmed to
+# be secret-free, and a final guard greps the staged output for secret patterns
+# and ABORTS if any are found (nothing is left in agent-shared on abort).
+#
+# bash 3.2 / BSD safe. Idempotent. --dry-run to preview.
+
+set -euo pipefail
+
+AGENT_SHARED="${HOME}/.agent-shared"
+DEST="${AGENT_SHARED}/agent-config"
+LOG_DIR="${HOME}/.youmd/logs"
+LOG_FILE="${LOG_DIR}/capture-agent-config.log"
+
+DRY_RUN=0
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    *) echo "Unknown flag: $arg" >&2; exit 1 ;;
+  esac
+done
+
+mkdir -p "${LOG_DIR}"
+log() { local ts; ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"; echo "[${ts}] $*"; echo "[${ts}] $*" >> "${LOG_FILE}"; }
+is_dry() { [ "${DRY_RUN}" -eq 1 ]; }
+
+if [ ! -d "${AGENT_SHARED}/.git" ]; then
+  log "ERROR: ${AGENT_SHARED} is not a git repo — run machine setup first."
+  exit 1
+fi
+
+# copy_in <src> <dest-subpath>  — copy a file/dir into the staging dest if it exists
+copy_in() {
+  local src="$1" rel="$2" target
+  target="${DEST}/${rel}"
+  if [ ! -e "${src}" ]; then return 0; fi
+  if is_dry; then log "DRY would capture ${src} → agent-config/${rel}"; return 0; fi
+  mkdir -p "$(dirname "${target}")"
+  if [ -d "${src}" ]; then
+    rsync -a --delete "${src}/" "${target}/"
+  else
+    cp "${src}" "${target}"
+  fi
+  log "captured ${src} → agent-config/${rel}"
+}
+
+log "=== capture-agent-config START ($([ "${DRY_RUN}" -eq 1 ] && echo DRY || echo LIVE)) ==="
+
+# ── Claude config (settings have no raw secrets; ~/.claude.json is EXCLUDED — vaulted) ──
+copy_in "${HOME}/.claude/settings.json"               "claude/settings.json"
+copy_in "${HOME}/.claude/settings.local.json"         "claude/settings.local.json"
+copy_in "${HOME}/.claude/commands"                    "claude/commands"
+copy_in "${HOME}/.claude/mcp.json"                    "claude/mcp.json"
+copy_in "${HOME}/.claude/plugins/installed_plugins.json" "claude/plugins/installed_plugins.json"
+
+# ── Codex config (config.toml only; auth.json is EXCLUDED — vaulted) ──
+copy_in "${HOME}/.codex/config.toml"                  "codex/config.toml"
+
+# ── Warp (no secrets) ──
+copy_in "${HOME}/.warp/settings.toml"                 "warp/settings.toml"
+copy_in "${HOME}/.warp/keybindings.yaml"              "warp/keybindings.yaml"
+
+# ── Orphaned ~/.agents skills (no repo of their own today) ──
+copy_in "${HOME}/.agents/skills/find-skills"          "agents-skills/find-skills"
+copy_in "${HOME}/.agents/skills/ui-ux-pro-max"        "agents-skills/ui-ux-pro-max"
+
+# ── Automations: launchd plists (HOME-templated) + crontab snapshot ──
+capture_plist() {
+  local label="$1" src="${HOME}/Library/LaunchAgents/$1.plist" target="${DEST}/automations/launchd/$1.plist"
+  if [ ! -f "${src}" ]; then return 0; fi
+  if is_dry; then log "DRY would capture plist ${label} (HOME-templated)"; return 0; fi
+  mkdir -p "$(dirname "${target}")"
+  sed "s|${HOME}|__HOME__|g" "${src}" > "${target}"
+  log "captured plist ${label} → agent-config/automations/launchd/${label}.plist"
+}
+capture_plist "com.youmd.skillstack-sync"
+capture_plist "com.youmd.identity-sync"
+capture_plist "com.houstongolden.agent-runtime-guard"
+
+if ! is_dry; then
+  mkdir -p "${DEST}/automations"
+  crontab -l 2>/dev/null > "${DEST}/automations/crontab.txt" || true
+  log "captured crontab → agent-config/automations/crontab.txt"
+fi
+
+# ── SECRET-LEAK GUARD — abort if anything captured looks like a live secret ──
+if ! is_dry && [ -d "${DEST}" ]; then
+  # Match real secret token shapes; allow bare key NAMES (KEY=) which are fine.
+  HITS="$(grep -rIlE 'sk-ant-[A-Za-z0-9_-]{20}|sk-[A-Za-z0-9]{32}|ghp_[A-Za-z0-9]{30}|gho_[A-Za-z0-9]{30}|Bearer [A-Za-z0-9._-]{20}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10}' "${DEST}" 2>/dev/null || true)"
+  if [ -n "${HITS}" ]; then
+    log "ABORT: possible secret(s) found in captured config — removing capture, nothing committed:"
+    log "${HITS}"
+    rm -rf "${DEST}"
+    exit 1
+  fi
+  log "secret-leak guard: clean (no live secret patterns in captured config)"
+fi
+
+log "=== capture-agent-config DONE ==="

package/scripts/skillstack-sync/context-sync.sh

@@ -0,0 +1,344 @@
+#!/usr/bin/env bash
+# context-sync.sh — per-project agent context syncer (cross-machine, code-safe)
+# Compatible: bash 3.2+, macOS BSD coreutils (NO mapfile, NO GNU mktemp flags)
+#
+# WHAT IT DOES
+# ============
+# For each of Houston's own git repos, commits ONLY the agent-context paths
+# (AGENTS.md, CLAUDE.md, project-context/, .claude/) and pull+pushes, so
+# agent context travels across machines without ever touching application code.
+#
+# SAFETY GUARANTEES
+# =================
+# 1. Only stages named context paths — NEVER uses `git add -A` or `git add .`
+# 2. Never stashes, resets, checks out, or cleans anything in the working tree
+# 3. Never touches a repo that is mid-merge or mid-rebase
+# 4. Never touches a repo with no `origin` remote
+# 5. If the working tree has uncommitted non-context changes, commits context
+#    locally but SKIPS pull/push to avoid merge conflicts touching his code;
+#    logs a clear "push manually" warning
+# 6. On pull conflict: aborts merge, skips push, logs loudly — never force
+# 7. Per-repo failures are non-fatal; the loop always continues
+# 8. --dry-run logs intended actions; writes nothing to disk
+#
+# WHAT IS EXCLUDED (by design)
+# =============================
+# - Third-party / fork repos (disler/*, coffeefuelbump/*, etc.) — Houston
+#   doesn't own the remote, so auto-pushing context there is wrong
+# - Repos with no origin remote or push-disabled remotes — detected at runtime
+# - gstack, agent-shared, scistack — covered by sync.sh (skillstack layer)
+#
+# Usage:
+#   ./context-sync.sh              # sync all context repos
+#   ./context-sync.sh --dry-run    # log intended actions only, write nothing
+#
+# Env overrides:
+#   CONTEXT_REPOS   space-separated list of repo DIRECTORY NAMES under
+#                   ~/Desktop/CODE_2025/ (not full paths)
+#   GIT_USER_NAME   commit author name  (default: Houston Golden)
+#   GIT_USER_EMAIL  commit author email (default: houston@bamf.ai)
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LOG_DIR="${HOME}/.youmd/logs"
+LOG_FILE="${LOG_DIR}/context-sync.log"
+
+GIT_USER_NAME="${GIT_USER_NAME:-Houston Golden}"
+GIT_USER_EMAIL="${GIT_USER_EMAIL:-houston@bamf.ai}"
+
+CODE_ROOT="${HOME}/Desktop/CODE_2025"
+
+# Curated list of Houston's OWN repos with rich agent context.
+# These all have houstongolden/* or hubify-projects/* remotes — confirmed safe
+# to push to. Override via env CONTEXT_REPOS (space-separated dir names).
+#
+# Excluded by design:
+#   - disler/*, coffeefuelbump/*, etc.  → not Houston's remote
+#   - repos with no origin              → detected and skipped at runtime
+#   - gstack, agent-shared, scistack    → handled by sync.sh
+DEFAULT_CONTEXT_REPOS="bamfaiapp bigbounce hubify-aios myo hubifycode badapp claws"
+CONTEXT_REPOS="${CONTEXT_REPOS:-${DEFAULT_CONTEXT_REPOS}}"
+
+# The ONLY paths we will ever stage. Nothing else is touched.
+CONTEXT_PATHSPECS="AGENTS.md CLAUDE.md project-context .claude"
+
+DRY_RUN=0
+
+# ---------------------------------------------------------------------------
+# Parse flags
+# ---------------------------------------------------------------------------
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    --once)    : ;;   # accepted for explicit invocation parity with sync.sh
+    *) echo "Unknown flag: $arg" >&2; exit 1 ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+mkdir -p "${LOG_DIR}"
+
+log() {
+  local ts
+  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  local msg="[${ts}] $*"
+  echo "${msg}"
+  echo "${msg}" >> "${LOG_FILE}"
+}
+
+log_warn() {
+  log "WARN  $*"
+}
+
+log_error() {
+  log "ERROR $*"
+}
+
+log_dry() {
+  log "DRY   $*"
+}
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+hostname_short() {
+  # BSD hostname (no --short flag on macOS)
+  hostname | cut -d. -f1
+}
+
+is_dry() {
+  [ "${DRY_RUN}" -eq 1 ]
+}
+
+# Check if repo is in a mid-merge/rebase state
+repo_is_in_progress() {
+  local repo="$1"
+  if [ -f "${repo}/.git/MERGE_HEAD" ] \
+     || [ -d "${repo}/.git/rebase-merge" ] \
+     || [ -d "${repo}/.git/rebase-apply" ]; then
+    return 0
+  fi
+  return 1
+}
+
+# Collect context pathspecs that actually exist in this repo.
+# Returns a space-separated list (possibly empty).
+existing_context_paths() {
+  local repo="$1"
+  local found=""
+  local p
+  for p in ${CONTEXT_PATHSPECS}; do
+    if [ -e "${repo}/${p}" ]; then
+      if [ -z "${found}" ]; then
+        found="${p}"
+      else
+        found="${found} ${p}"
+      fi
+    fi
+  done
+  echo "${found}"
+}
+
+# ---------------------------------------------------------------------------
+# SYNC ONE REPO
+# Returns 0 on success, 1 on non-fatal failure.
+#
+# Pull/push safety decision (dirty non-context working tree):
+# ============================================================
+# After committing context changes, the working tree may still have untracked
+# or modified files (Houston's WIP code). A `git pull` that brings in remote
+# changes could attempt to merge those dirty files, causing conflicts or
+# accidentally modifying them. The SAFE choice:
+#   - If the working tree has ANY remaining dirty files after the context
+#     commit, SKIP pull/push and log a clear warning.
+#   - The context commit is still made locally, so the changes are preserved
+#     and Houston can push manually when he's ready.
+#   - We never stash, reset, or touch his code.
+# ---------------------------------------------------------------------------
+sync_context_repo() {
+  local repo_name="$1"
+  local repo="${CODE_ROOT}/${repo_name}"
+
+  log "=== Syncing context for: ${repo_name} ==="
+
+  # Guard: directory must exist
+  if [ ! -d "${repo}" ]; then
+    log_warn "Skipping ${repo_name}: directory not found at ${repo}."
+    return 1
+  fi
+
+  # Guard: must be a git repo
+  if [ ! -d "${repo}/.git" ]; then
+    log_warn "Skipping ${repo_name}: not a git repository."
+    return 1
+  fi
+
+  # Guard: must not be mid-merge/rebase
+  if repo_is_in_progress "${repo}"; then
+    log_warn "Skipping ${repo_name}: repository is mid-merge or mid-rebase. Resolve manually first."
+    return 1
+  fi
+
+  # Guard: must have an origin remote
+  if ! git -C "${repo}" remote get-url origin >/dev/null 2>&1; then
+    log_warn "Skipping ${repo_name}: no 'origin' remote configured."
+    return 1
+  fi
+
+  # Determine which context paths exist in this repo
+  local paths
+  paths="$(existing_context_paths "${repo}")"
+
+  if [ -z "${paths}" ]; then
+    log "No context paths found in ${repo_name} (none of: ${CONTEXT_PATHSPECS}). Skipping."
+    return 0
+  fi
+
+  log "Context paths present in ${repo_name}: ${paths}"
+
+  # ---- Stage ONLY the context paths (never git add -A or git add .) --------
+  if is_dry; then
+    log_dry "Would stage in ${repo_name}: ${paths}"
+  else
+    # Build the git add command with only existing paths.
+    # We pass each path as a separate argument — safe because they come from
+    # our controlled CONTEXT_PATHSPECS list, not user input.
+    local add_args=""
+    local p
+    for p in ${paths}; do
+      add_args="${add_args} ${p}"
+    done
+    # shellcheck disable=SC2086
+    git -C "${repo}" add -- ${add_args}
+    log "Staged context paths in ${repo_name}: ${paths}"
+  fi
+
+  # ---- Commit if staged changes exist ---------------------------------------
+  local context_committed=0
+  if is_dry; then
+    log_dry "Would check for staged changes and commit context in ${repo_name} if any"
+    context_committed=1
+  else
+    if ! git -C "${repo}" diff --cached --quiet 2>/dev/null; then
+      local ts host commit_msg
+      ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+      host="$(hostname_short)"
+      commit_msg="context-sync: ${host} ${ts}"
+
+      git -C "${repo}" \
+        -c "user.name=${GIT_USER_NAME}" \
+        -c "user.email=${GIT_USER_EMAIL}" \
+        commit -m "${commit_msg}"
+      log "Committed context changes in ${repo_name}: '${commit_msg}'"
+      context_committed=1
+    else
+      log "No staged context changes in ${repo_name} (already up to date)."
+      context_committed=0
+    fi
+  fi
+
+  # ---- Check for remaining dirty working tree (WIP code) -------------------
+  # After committing context, if there are still dirty files, skip pull/push
+  # to avoid merge conflicts or accidental code modification.
+  if ! is_dry; then
+    local remaining_dirty
+    remaining_dirty="$(git -C "${repo}" status --porcelain 2>/dev/null)"
+    if [ -n "${remaining_dirty}" ]; then
+      log_warn "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+      log_warn "${repo_name} has uncommitted non-context changes (WIP code)."
+      log_warn "Context was committed locally. Skipping pull/push to avoid"
+      log_warn "touching your code. Push manually when your code is ready:"
+      log_warn "  cd ${repo} && git pull --no-rebase && git push"
+      log_warn "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+      return 0
+    fi
+  fi
+
+  # ---- Pull (merge, no rebase) ---------------------------------------------
+  if is_dry; then
+    log_dry "Would git pull --no-rebase --no-edit in ${repo_name}"
+  else
+    local pull_log
+    # BSD mktemp: no -p, use /tmp explicitly
+    pull_log="$(mktemp -t context_sync_pull)"
+    local pull_ok=0
+    git -C "${repo}" pull --no-rebase --no-edit >"${pull_log}" 2>&1 || pull_ok=$?
+
+    while IFS= read -r line; do
+      log "pull|${repo_name}: ${line}"
+    done < "${pull_log}"
+    rm -f "${pull_log}"
+
+    if [ "${pull_ok}" -ne 0 ]; then
+      log_error "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+      log_error "CONFLICT in ${repo_name} — pull failed."
+      log_error "Aborting merge and skipping push."
+      log_error "Manual resolution needed: cd ${repo} && git status"
+      log_error "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+      git -C "${repo}" merge --abort 2>/dev/null || true
+      git -C "${repo}" rebase --abort 2>/dev/null || true
+      return 1
+    fi
+    log "Pull succeeded for ${repo_name}."
+  fi
+
+  # ---- Push ----------------------------------------------------------------
+  if is_dry; then
+    log_dry "Would git push in ${repo_name}"
+  else
+    local push_log
+    push_log="$(mktemp -t context_sync_push)"
+    local push_ok=0
+    git -C "${repo}" push >"${push_log}" 2>&1 || push_ok=$?
+
+    while IFS= read -r line; do
+      log "push|${repo_name}: ${line}"
+    done < "${push_log}"
+    rm -f "${push_log}"
+
+    if [ "${push_ok}" -ne 0 ]; then
+      log_error "Push FAILED for ${repo_name}. Check connectivity/auth."
+      return 1
+    fi
+    log "Push succeeded for ${repo_name}."
+  fi
+
+  log "=== Done: ${repo_name} ==="
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# MAIN
+# ---------------------------------------------------------------------------
+main() {
+  local mode
+  if is_dry; then
+    mode="DRY-RUN"
+  else
+    mode="LIVE"
+  fi
+
+  log "============================================================"
+  log "context-sync START [${mode}] on $(hostname_short)"
+  log "Repos: ${CONTEXT_REPOS}"
+  log "Context paths: ${CONTEXT_PATHSPECS}"
+  log "============================================================"
+
+  local repo_name
+  for repo_name in ${CONTEXT_REPOS}; do
+    sync_context_repo "${repo_name}" || true
+  done
+
+  log "============================================================"
+  log "context-sync DONE [${mode}]"
+  log "============================================================"
+}
+
+main "$@"