youmd 0.8.0 → 0.8.2

package/scripts/env-vault/README.md

@@ -28,6 +28,9 @@ top of `backup.sh` and add the matching entry to `AGENT_AUTH_MAP` in
 # via CLI (preferred — ships in the npm package)
 youmd env backup
 
+# Check local encryption tooling and env discovery without writing a vault:
+youmd env backup --preflight
+
 # or directly via bash (from the youmd repo root)
 cd /Users/houstongolden/Desktop/CODE_2025/youmd
 bash cli/scripts/env-vault/backup.sh
@@ -52,6 +55,7 @@ Do NOT transfer via unencrypted email or public Slack.
 
 ```bash
 # Install dependencies first (e.g. Node, pnpm, etc.), then:
+youmd env restore /path/to/env-vault-<date>.tar.<ext> --list
 youmd env restore /path/to/env-vault-<date>.tar.<ext>
 
 # If files already exist on the new Mac:
@@ -63,10 +67,12 @@ bash cli/scripts/env-vault/restore.sh --force /path/to/env-vault-<date>.tar.<ext
 ```
 
 The script:
-1. Creates `<CODE_2025>/<project>/.env.local` for each project.
-2. Restores agent-auth files to their absolute home paths (`~/.codex/auth.json`, `~/.cursor/mcp.json`, `~/.claude.json`), creating parent directories as needed.
+1. Lists vault contents without writing files when `--list` is provided.
+2. Creates `<CODE_2025>/<project>/.env.local` for each project during restore.
+3. Restores agent-auth files to their absolute home paths (`~/.codex/auth.json`, `~/.cursor/mcp.json`, `~/.claude.json`), creating parent directories as needed.
 
 Existing files are backed up to `<path>.bak.<timestamp>` before overwrite (or silently overwritten with `--force`).
+List mode prints project env target paths, variable names/counts, and agent-auth file presence only. It never prints secret values.
 
 ---
 
@@ -101,10 +107,12 @@ and are exposed as first-class CLI commands:
 
 ```bash
 youmd env backup                # back up all .env.local files
+youmd env backup --preflight    # verify tooling/discovery without writing
 youmd env backup --root <dir>   # custom search root
 youmd env backup --out <dir>    # custom output dir
 
 youmd env restore <vault>       # restore from an encrypted vault
+youmd env restore <vault> --list # list vault contents without writing
 youmd env restore --force       # overwrite existing .env.local files
 youmd env restore --root <dir>  # restore into a custom root
 ```
@@ -121,6 +129,7 @@ your terminal unchanged.
 
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--preflight` | off | Verify encryption tooling/discovery without writing a vault |
 | `--root <dir>` | `~/Desktop/CODE_2025` | Where to discover `.env.local` files |
 | `--out <dir>` | `youmd/.env-vault/` | Where to write encrypted vault + manifest |
 
@@ -128,6 +137,7 @@ your terminal unchanged.
 
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--list` | off | List vault contents without writing files |
 | `--root <dir>` | `~/Desktop/CODE_2025` | Where to restore project `.env.local` files |
 | `--force` | off | Overwrite existing `.env.local` instead of skipping |
 

package/scripts/env-vault/backup.sh

@@ -4,7 +4,7 @@
 # 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>]
+# Usage: bash backup.sh [--preflight] [--root <search-root>] [--out <output-dir>]
 # Defaults:
 #   search-root: /Users/houstongolden/Desktop/CODE_2025
 #   output-dir:  /Users/houstongolden/Desktop/CODE_2025/youmd/.env-vault
@@ -14,6 +14,7 @@ set -euo pipefail
 # ── configurable defaults ──────────────────────────────────────────────────────
 SEARCH_ROOT="${ENV_VAULT_ROOT:-/Users/houstongolden/Desktop/CODE_2025}"
 OUTPUT_DIR="${ENV_VAULT_OUT:-/Users/houstongolden/Desktop/CODE_2025/youmd/.env-vault}"
+PREFLIGHT=false
 
 # ── agent-auth secret files ────────────────────────────────────────────────────
 # Absolute paths to hard agent-auth secrets that must travel with the vault.
@@ -28,6 +29,7 @@ AGENT_SECRET_FILES=(
 # ── parse flags ────────────────────────────────────────────────────────────────
 while [[ $# -gt 0 ]]; do
   case $1 in
+    --preflight) PREFLIGHT=true; shift ;;
     --root)  SEARCH_ROOT="$2"; shift 2 ;;
     --out)   OUTPUT_DIR="$2";  shift 2 ;;
     *) echo "Unknown flag: $1" >&2; exit 1 ;;
@@ -66,11 +68,32 @@ done < <(find "${SEARCH_ROOT}" -maxdepth 2 -name ".env.local" -print0 2>/dev/nul
 
 if [[ ${#ENV_FILES[@]} -eq 0 ]]; then
   echo "No .env.local files found under ${SEARCH_ROOT}" >&2
+  if [[ "${PREFLIGHT}" == "true" ]]; then
+    echo "Preflight only: encryption tooling is available, but no .env.local files were found."
+    exit 0
+  fi
   exit 1
 fi
 
 echo "Found ${#ENV_FILES[@]} .env.local file(s)."
 
+if [[ "${PREFLIGHT}" == "true" ]]; then
+  echo "Output dir: ${OUTPUT_DIR}"
+  echo "Agent-auth candidates:"
+  for ENTRY in "${AGENT_SECRET_FILES[@]}"; do
+    SRC_PATH="${ENTRY%%:*}"
+    ARCHIVE_NAME="${ENTRY##*:}"
+    if [[ -f "${SRC_PATH}" ]]; then
+      FILE_BYTES=$(wc -c < "${SRC_PATH}" | tr -d ' ')
+      echo "  present: agent-auth/${ARCHIVE_NAME} (${FILE_BYTES} bytes)"
+    else
+      echo "  missing: agent-auth/${ARCHIVE_NAME}"
+    fi
+  done
+  echo "Preflight only: no vault written and no secret values printed."
+  exit 0
+fi
+
 # ── build plaintext manifest (names + counts, NO values) ─────────────────────
 mkdir -p "${OUTPUT_DIR}"
 UTC_DATE="$(date -u +%Y-%m-%dT%H%MZ)"

package/scripts/env-vault/restore.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 # 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.
+# secret VALUES. Restore prints which file paths were restored or skipped; list
+# mode prints target paths plus variable names/counts only.
 #
-# Usage: bash restore.sh [--force] [--root <target-root>] <vault-file>
+# Usage: bash restore.sh [--list] [--force] [--root <target-root>] <vault-file>
 #   vault-file: path to env-vault-*.tar.age / .tar.gpg / .tar.enc
 #   --force:    overwrite existing files without backing them up
 #   --root:     destination root for .env.local files
@@ -29,11 +30,13 @@ AGENT_AUTH_MAP=(
 # ── defaults ──────────────────────────────────────────────────────────────────
 TARGET_ROOT="${ENV_VAULT_RESTORE_ROOT:-/Users/houstongolden/Desktop/CODE_2025}"
 FORCE=false
+LIST_ONLY=false
 VAULT_FILE=""
 
 # ── parse args ─────────────────────────────────────────────────────────────────
 while [[ $# -gt 0 ]]; do
   case $1 in
+    --list)   LIST_ONLY=true; shift ;;
     --force)  FORCE=true; shift ;;
     --root)   TARGET_ROOT="$2"; shift 2 ;;
     -*)       echo "Unknown flag: $1" >&2; exit 1 ;;
@@ -49,7 +52,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 if [[ -z "${VAULT_FILE}" ]]; then
-  echo "Usage: bash restore.sh [--force] [--root <path>] <vault-file>" >&2
+  echo "Usage: bash restore.sh [--list] [--force] [--root <path>] <vault-file>" >&2
   echo "  vault-file: env-vault-*.tar.age | .tar.gpg | .tar.enc" >&2
   exit 1
 fi
@@ -119,6 +122,45 @@ EXTRACT_DIR="${WORK_DIR}/extracted"
 mkdir -p "${EXTRACT_DIR}"
 tar -xf "${TAR_PATH}" -C "${EXTRACT_DIR}"
 
+if [[ "${LIST_ONLY}" == "true" ]]; then
+  ENV_COUNT=0
+  AGENT_PRESENT=0
+  AGENT_MISSING=0
+
+  echo "Vault contents (secret-safe inventory):"
+  while IFS= read -r -d '' ENV_FILE; do
+    REL_PATH="${ENV_FILE#${EXTRACT_DIR}/}"
+    PROJECT_NAME="$(dirname "${REL_PATH}")"
+    DEST="${TARGET_ROOT}/${PROJECT_NAME}/.env.local"
+    VAR_COUNT=$(grep -cE '^[A-Za-z_][A-Za-z0-9_]*=' "${ENV_FILE}" 2>/dev/null || true)
+    VAR_NAMES=$(grep -oE '^[A-Za-z_][A-Za-z0-9_]*' "${ENV_FILE}" 2>/dev/null \
+                | grep -v '^$' | sort | paste -sd ',' - || true)
+    echo "  env: ${PROJECT_NAME}/.env.local -> ${DEST} (${VAR_COUNT} variable(s) [${VAR_NAMES}])"
+    (( ENV_COUNT++ )) || true
+  done < <(find "${EXTRACT_DIR}" -name ".env.local" -print0)
+
+  AGENT_AUTH_SRC="${EXTRACT_DIR}/agent-auth"
+  echo "  agent-auth:"
+  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
+      FILE_BYTES=$(wc -c < "${SRC_FILE}" | tr -d ' ')
+      echo "    present: agent-auth/${ARCHIVE_NAME} -> ${DEST_PATH} (${FILE_BYTES} bytes)"
+      (( AGENT_PRESENT++ )) || true
+    else
+      echo "    missing: agent-auth/${ARCHIVE_NAME}"
+      (( AGENT_MISSING++ )) || true
+    fi
+  done
+
+  echo ""
+  echo "List summary: ${ENV_COUNT} .env.local file(s), ${AGENT_PRESENT} agent-auth file(s) present, ${AGENT_MISSING} agent-auth file(s) missing."
+  echo "No files were written and no secret values were printed."
+  exit 0
+fi
+
 # ── restore each .env.local ───────────────────────────────────────────────────
 RESTORED=0
 SKIPPED=0

package/scripts/skillstack-sync/README.md

@@ -28,7 +28,8 @@ Cross-machine sync toolkit for Houston Golden's agent skill/stack setup.
 
 ### Complementary sync planes
 
-- **Identity plane:** `youmd sync` (Convex ↔ local profile, memories, preferences). Automated via `com.youmd.identity-sync` daemon.
+- **Identity plane:** `youmd sync --daemon` (Convex ↔ local profile, memories, preferences). Automated via `com.youmd.identity-sync` daemon. Daemon mode refreshes local files/skills and skips unsafe lossy pushes instead of forcing over richer server data.
+- **Project-context plane:** `youmd stack context-sync` safely commits and syncs only `AGENTS.md`, `CLAUDE.md`, `project-context/`, and `.claude/` in curated Houston-owned repos. It refuses to merge remote app-code changes.
 - **Env-vault plane:** `cli/scripts/env-vault/restore.sh` for secrets (manual, invoked on new machine); also available as `youmd env restore <vault>`.
 
 ---
@@ -38,10 +39,11 @@ Cross-machine sync toolkit for Houston Golden's agent skill/stack setup.
 ```
 cli/scripts/skillstack-sync/
 ├── sync.sh                         Core syncer (bash 3.2 compatible)
-├── install-daemons.sh              Installs both LaunchAgents
+├── install-daemons.sh              Installs all resident LaunchAgents
 ├── bootstrap-new-mac.sh            New machine setup script
 ├── com.youmd.skillstack-sync.plist LaunchAgent: runs `youmd stack sync` every 5 min
-├── com.youmd.identity-sync.plist   LaunchAgent: runs `youmd sync` every 5 min
+├── com.youmd.identity-sync.plist   LaunchAgent: runs `youmd sync --daemon` every 5 min
+├── com.youmd.context-sync.plist    LaunchAgent: runs `youmd stack context-sync` every 15 min
 └── README.md                       This file
 ```
 
@@ -90,7 +92,7 @@ GIT_USER_EMAIL="houston@bamf.ai"                    # commit email (default)
 The preferred way is via the CLI:
 
 ```bash
-youmd stack daemon install    # installs both LaunchAgents
+youmd stack daemon install    # installs all resident LaunchAgents
 youmd stack daemon status     # check loaded/not-loaded
 youmd stack daemon uninstall  # remove plists from ~/Library/LaunchAgents/
 ```
@@ -101,9 +103,10 @@ Or run the raw script directly:
 bash cli/scripts/skillstack-sync/install-daemons.sh
 ```
 
-Installs two LaunchAgents that fire every 300 seconds (5 minutes):
+Installs three LaunchAgents:
 - `com.youmd.skillstack-sync` → runs `youmd stack sync`
-- `com.youmd.identity-sync` → runs `youmd sync`
+- `com.youmd.identity-sync` → runs `youmd sync --daemon`
+- `com.youmd.context-sync` → runs `youmd stack context-sync`
 
 Check status:
 ```bash
@@ -111,6 +114,7 @@ youmd stack daemon status
 # or directly:
 launchctl list com.youmd.skillstack-sync
 launchctl list com.youmd.identity-sync
+launchctl list com.youmd.context-sync
 ```
 
 Check logs:
@@ -118,6 +122,7 @@ Check logs:
 tail -f ~/.youmd/logs/skillstack-sync.log
 tail -f ~/.youmd/logs/skillstack-sync.out.log
 tail -f ~/.youmd/logs/identity-sync.out.log
+tail -f ~/.youmd/logs/context-sync.log
 ```
 
 ### Uninstall daemons
@@ -130,8 +135,10 @@ Or manually:
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.youmd.skillstack-sync.plist
 launchctl unload ~/Library/LaunchAgents/com.youmd.identity-sync.plist
+launchctl unload ~/Library/LaunchAgents/com.youmd.context-sync.plist
 rm ~/Library/LaunchAgents/com.youmd.skillstack-sync.plist
 rm ~/Library/LaunchAgents/com.youmd.identity-sync.plist
+rm ~/Library/LaunchAgents/com.youmd.context-sync.plist
 ```
 
 ---

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

@@ -85,6 +85,7 @@ capture_plist() {
 }
 capture_plist "com.youmd.skillstack-sync"
 capture_plist "com.youmd.identity-sync"
+capture_plist "com.youmd.context-sync"
 capture_plist "com.houstongolden.agent-runtime-guard"
 
 if ! is_dry; then

package/scripts/skillstack-sync/com.youmd.context-sync.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>com.youmd.context-sync</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/zsh</string>
+        <string>-lc</string>
+        <string>youmd stack context-sync</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>900</integer>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <false/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.youmd/logs/context-sync.out.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.youmd/logs/context-sync.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>__HOME__</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>

package/scripts/skillstack-sync/com.youmd.identity-sync.plist

@@ -9,7 +9,7 @@
     <array>
         <string>/bin/zsh</string>
         <string>-lc</string>
-        <string>youmd sync</string>
+        <string>youmd sync --daemon</string>
     </array>
 
     <key>StartInterval</key>
@@ -31,6 +31,8 @@
     <dict>
         <key>HOME</key>
         <string>__HOME__</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
     </dict>
 </dict>
 </plist>

package/scripts/skillstack-sync/com.youmd.skillstack-sync.plist

@@ -32,7 +32,7 @@
         <key>HOME</key>
         <string>__HOME__</string>
         <key>PATH</key>
-        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
     </dict>
 </dict>
 </plist>

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

@@ -146,6 +146,49 @@ existing_context_paths() {
   echo "${found}"
 }
 
+path_is_context() {
+  local changed="$1"
+  local p
+  for p in ${CONTEXT_PATHSPECS}; do
+    if [ "${changed}" = "${p}" ]; then
+      return 0
+    fi
+    case "${changed}" in
+      "${p}/"*) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+remote_has_non_context_changes() {
+  local repo="$1" repo_name="$2" upstream="$3"
+  local changed non_context line
+  changed="$(git -C "${repo}" diff --name-only "HEAD..${upstream}" 2>/dev/null || true)"
+  if [ -z "${changed}" ]; then
+    return 1
+  fi
+
+  non_context=""
+  while IFS= read -r line; do
+    [ -z "${line}" ] && continue
+    if ! path_is_context "${line}"; then
+      if [ -z "${non_context}" ]; then
+        non_context="${line}"
+      else
+        non_context="${non_context}, ${line}"
+      fi
+    fi
+  done <<EOF
+${changed}
+EOF
+
+  if [ -n "${non_context}" ]; then
+    log_warn "${repo_name}: upstream has non-context changes (${non_context}). Skipping pull/push so context-sync never merges application code."
+    return 0
+  fi
+  return 1
+}
+
 # ---------------------------------------------------------------------------
 # SYNC ONE REPO
 # Returns 0 on success, 1 on non-fatal failure.
@@ -263,8 +306,33 @@ sync_context_repo() {
 
   # ---- Pull (merge, no rebase) ---------------------------------------------
   if is_dry; then
-    log_dry "Would git pull --no-rebase --no-edit in ${repo_name}"
+    log_dry "Would fetch upstream and pull only if remote changes are limited to context paths in ${repo_name}"
   else
+    local upstream
+    upstream="$(git -C "${repo}" rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || true)"
+    if [ -z "${upstream}" ]; then
+      log_warn "Skipping pull/push for ${repo_name}: no upstream branch configured."
+      return 0
+    fi
+
+    local fetch_log
+    fetch_log="$(mktemp -t context_sync_fetch)"
+    local fetch_ok=0
+    git -C "${repo}" fetch --quiet >"${fetch_log}" 2>&1 || fetch_ok=$?
+    if [ "${fetch_ok}" -ne 0 ]; then
+      while IFS= read -r line; do
+        log "fetch|${repo_name}: ${line}"
+      done < "${fetch_log}"
+      rm -f "${fetch_log}"
+      log_error "Fetch FAILED for ${repo_name}. Skipping pull/push."
+      return 1
+    fi
+    rm -f "${fetch_log}"
+
+    if remote_has_non_context_changes "${repo}" "${repo_name}" "${upstream}"; then
+      return 0
+    fi
+
     local pull_log
     # BSD mktemp: no -p, use /tmp explicitly
     pull_log="$(mktemp -t context_sync_pull)"

package/scripts/skillstack-sync/install-daemons.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# install-daemons.sh — install skillstack-sync and identity-sync LaunchAgents
+# install-daemons.sh — install resident You.md sync LaunchAgents
 #
 # Idempotent: safe to re-run. Unloads before reloading.
 # Does NOT need sudo — LaunchAgents run as the current user.
@@ -12,7 +12,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LAUNCH_AGENTS_DIR="${HOME}/Library/LaunchAgents"
 LOG_DIR="${HOME}/.youmd/logs"
 
-PLISTS="com.youmd.skillstack-sync com.youmd.identity-sync"
+PLISTS="com.youmd.skillstack-sync com.youmd.identity-sync com.youmd.context-sync"
 
 echo "==> Creating log directory: ${LOG_DIR}"
 mkdir -p "${LOG_DIR}"
@@ -55,7 +55,7 @@ done
 
 echo ""
 echo "================================================================"
-echo "Both daemons installed and running."
+echo "Resident You.md daemons installed and running."
 echo ""
 echo "Log files:"
 echo "  ${LOG_DIR}/skillstack-sync.log      (combined sync log)"
@@ -63,10 +63,14 @@ echo "  ${LOG_DIR}/skillstack-sync.out.log  (daemon stdout)"
 echo "  ${LOG_DIR}/skillstack-sync.err.log  (daemon stderr)"
 echo "  ${LOG_DIR}/identity-sync.out.log    (youmd sync stdout)"
 echo "  ${LOG_DIR}/identity-sync.err.log    (youmd sync stderr)"
+echo "  ${LOG_DIR}/context-sync.log         (combined project-context sync log)"
+echo "  ${LOG_DIR}/context-sync.out.log     (daemon stdout)"
+echo "  ${LOG_DIR}/context-sync.err.log     (daemon stderr)"
 echo ""
 echo "Check daemon status:"
 echo "  launchctl list com.youmd.skillstack-sync"
 echo "  launchctl list com.youmd.identity-sync"
+echo "  launchctl list com.youmd.context-sync"
 echo ""
 echo "To uninstall:"
 for label in ${PLISTS}; do