youmd 0.6.27 → 0.7.0

package/scripts/check-version-exists.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// T29: pre-publish guard — refuse to attempt `npm publish` if the version in
+// package.json already exists on the npm registry. npm itself errors out with
+// E_PUBLISH_CONFLICT, but only after build + tarball + 2FA dance — surfacing
+// the conflict up-front saves the OTP round-trip every time someone forgets
+// `npm version patch`.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(__dirname, "..", "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+const name = pkg.name;
+const version = pkg.version;
+
+const url = `https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}`;
+
+try {
+  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+  if (res.status === 404) {
+    // unknown version — safe to publish
+    process.exit(0);
+  }
+  if (res.ok) {
+    console.error(
+      `\n  ✗ ${name}@${version} is already published on npm.\n` +
+      `    bump the version before publishing:\n\n` +
+      `      cd cli && npm version patch --no-git-tag-version\n\n`
+    );
+    process.exit(1);
+  }
+  // 5xx or transient — don't block the publish on registry flakiness; warn and continue
+  console.error(`  ! could not reach npm registry (HTTP ${res.status}) — proceeding without version check`);
+  process.exit(0);
+} catch (err) {
+  console.error(`  ! could not reach npm registry (${err?.message ?? err}) — proceeding without version check`);
+  process.exit(0);
+}

package/scripts/env-vault/README.md

@@ -0,0 +1,123 @@
+# env-vault — Secure .env.local Backup & Restore
+
+Backs up all `.env.local` files across your CODE_2025 projects into a single
+encrypted archive, and restores them on a new Mac. No secret values ever appear
+in plaintext outside the encrypted blob.
+
+---
+
+## New-Machine Flow
+
+### On the old Mac (backup)
+
+```bash
+# via CLI (preferred — ships in the npm package)
+youmd env backup
+
+# or directly via bash (from the youmd repo root)
+cd /Users/houstongolden/Desktop/CODE_2025/youmd
+bash cli/scripts/env-vault/backup.sh
+```
+
+This writes two files to `.env-vault/`:
+- `env-vault-<date>.tar.<ext>` — encrypted archive (safe to transport)
+- `manifest-<date>.txt` — variable names + counts only (safe to read, no values)
+
+You will be prompted for a passphrase. Store it in **1Password** immediately.
+
+### Transfer to new Mac
+
+Options (all safe — the file is encrypted):
+1. **AirDrop** the `.tar.<ext>` file directly
+2. **USB drive** — copy to a thumb drive, plug into new Mac
+3. **iCloud Drive** — upload briefly, download on new Mac, then delete from cloud
+
+Do NOT transfer via unencrypted email or public Slack.
+
+### On the new Mac (restore)
+
+```bash
+# Install dependencies first (e.g. Node, pnpm, etc.), then:
+youmd env restore /path/to/env-vault-<date>.tar.<ext>
+
+# If project dirs already exist with .env.local files:
+youmd env restore --force /path/to/env-vault-<date>.tar.<ext>
+
+# or directly via bash:
+bash cli/scripts/env-vault/restore.sh /path/to/env-vault-<date>.tar.<ext>
+bash cli/scripts/env-vault/restore.sh --force /path/to/env-vault-<date>.tar.<ext>
+```
+
+The script creates `<CODE_2025>/<project>/.env.local` for each project.
+Existing files are backed up to `.env.local.bak.<timestamp>` (or overwritten with `--force`).
+
+---
+
+## 3-Location Backup Rule
+
+Your encrypted vault should live in **at least 3 locations**:
+
+| Location | Example |
+|----------|---------|
+| Local machine | `.env-vault/` (already done by backup.sh) |
+| Secure cloud | 1Password attachment, private iCloud folder |
+| Physical backup | USB drive stored separately from your Mac |
+
+The encrypted file itself is safe to store anywhere. The passphrase is the secret.
+
+---
+
+## Security Model
+
+- **Encryption:** `age` (preferred) → `gpg AES-256` → `openssl AES-256-CBC PBKDF2`
+- **What's in the encrypted archive:** full `.env.local` file contents
+- **What's in plaintext:** only the project name + variable NAMES + count (the manifest)
+- **Values:** never printed, echoed, logged, or written anywhere outside the encrypted blob
+- **Passphrase:** stored nowhere by these scripts — you must store it in 1Password
+
+---
+
+## CLI Integration
+
+These scripts ship inside the `youmd` npm package (`cli/scripts/env-vault/`)
+and are exposed as first-class CLI commands:
+
+```bash
+youmd env backup                # back up all .env.local files
+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 --force       # overwrite existing .env.local files
+youmd env restore --root <dir>  # restore into a custom root
+```
+
+The CLI wrapper delegates directly to these bash scripts via `spawnSync` with
+`stdio: "inherit"` so the passphrase prompt and all output pass through to
+your terminal unchanged.
+
+---
+
+## Flags
+
+### backup.sh
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--root <dir>` | `~/Desktop/CODE_2025` | Where to discover `.env.local` files |
+| `--out <dir>` | `youmd/.env-vault/` | Where to write encrypted vault + manifest |
+
+### restore.sh
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--root <dir>` | `~/Desktop/CODE_2025` | Where to restore project `.env.local` files |
+| `--force` | off | Overwrite existing `.env.local` instead of skipping |
+
+---
+
+## .gitignore Note
+
+The `.env-vault/` output directory is listed in `youmd/.gitignore`. Encrypted
+vault files are **never committed to git**. Only the scripts and this README
+are tracked.

package/scripts/env-vault/backup.sh

@@ -0,0 +1,167 @@
+#!/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.
+#
+# Usage: bash backup.sh [--root <search-root>] [--out <output-dir>]
+# Defaults:
+#   search-root: /Users/houstongolden/Desktop/CODE_2025
+#   output-dir:  /Users/houstongolden/Desktop/CODE_2025/youmd/.env-vault
+
+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}"
+
+# ── parse flags ────────────────────────────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --root)  SEARCH_ROOT="$2"; shift 2 ;;
+    --out)   OUTPUT_DIR="$2";  shift 2 ;;
+    *) echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+# ── detect encryption tool ────────────────────────────────────────────────────
+# Prefer openssl: it ships on every macOS install, so a vault encrypted with it
+# can ALWAYS be restored on a brand-new Mac (which may not have age or gpg). The
+# others are used only if openssl is somehow unavailable. Set ENV_VAULT_PASS to
+# run non-interactively (e.g. from automation); otherwise you'll be prompted.
+ENC_TOOL=""
+ENC_EXT=""
+if command -v openssl &>/dev/null; then
+  ENC_TOOL="openssl"
+  ENC_EXT="enc"
+elif command -v age &>/dev/null; then
+  ENC_TOOL="age"
+  ENC_EXT="age"
+elif command -v gpg &>/dev/null; then
+  ENC_TOOL="gpg"
+  ENC_EXT="gpg"
+else
+  echo "ERROR: No encryption tool found. Install age, gpg, or openssl." >&2
+  exit 1
+fi
+
+echo "Encryption tool: ${ENC_TOOL}"
+
+# ── discover .env.local files (handles spaces in dir names) ───────────────────
+# bash 3.2 (macOS default) has no `mapfile`, so build the array with read -d ''.
+ENV_FILES=()
+while IFS= read -r -d '' _envf; do
+  ENV_FILES+=("${_envf}")
+done < <(find "${SEARCH_ROOT}" -maxdepth 2 -name ".env.local" -print0 2>/dev/null)
+
+if [[ ${#ENV_FILES[@]} -eq 0 ]]; then
+  echo "No .env.local files found under ${SEARCH_ROOT}" >&2
+  exit 1
+fi
+
+echo "Found ${#ENV_FILES[@]} .env.local file(s)."
+
+# ── build plaintext manifest (names + counts, NO values) ─────────────────────
+mkdir -p "${OUTPUT_DIR}"
+UTC_DATE="$(date -u +%Y-%m-%dT%H%MZ)"
+MANIFEST_PATH="${OUTPUT_DIR}/manifest-${UTC_DATE}.txt"
+
+{
+  echo "env-vault manifest — ${UTC_DATE}"
+  echo "Encryption: ${ENC_TOOL}"
+  echo "Search root: ${SEARCH_ROOT}"
+  echo "---"
+} > "${MANIFEST_PATH}"
+
+# ── stage files into a temp dir preserving project-relative paths ─────────────
+STAGING_DIR="$(mktemp -d)"
+trap 'rm -rf "${STAGING_DIR}"' EXIT
+
+for ENV_FILE in "${ENV_FILES[@]}"; do
+  PROJECT_DIR="$(dirname "${ENV_FILE}")"
+  PROJECT_NAME="$(basename "${PROJECT_DIR}")"
+
+  # Store as <project-name>/.env.local inside the archive
+  DEST="${STAGING_DIR}/${PROJECT_NAME}"
+  mkdir -p "${DEST}"
+  cp "${ENV_FILE}" "${DEST}/.env.local"
+
+  # Count variable names only — never read values
+  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 "${PROJECT_NAME}/.env.local: ${VAR_COUNT} variable(s) [${VAR_NAMES}]" \
+    >> "${MANIFEST_PATH}"
+done
+
+echo "" >> "${MANIFEST_PATH}"
+echo "SECURITY: The encrypted archive is safe to transport. Keep the passphrase private." \
+  >> "${MANIFEST_PATH}"
+
+# ── create tar from staging dir ───────────────────────────────────────────────
+# BSD mktemp (macOS) has no --suffix; the tar path is temporary and deleted
+# after encryption, so a plain mktemp is fine.
+TAR_PATH="$(mktemp)"
+tar -cf "${TAR_PATH}" -C "${STAGING_DIR}" .
+
+VAULT_PATH="${OUTPUT_DIR}/env-vault-${UTC_DATE}.tar.${ENC_EXT}"
+
+# ── encrypt ───────────────────────────────────────────────────────────────────
+echo ""
+echo "Enter a strong passphrase to encrypt the vault."
+echo "(You will need this passphrase to restore on a new machine — store it safely.)"
+echo ""
+
+case "${ENC_TOOL}" in
+  openssl)
+    if [[ -n "${ENV_VAULT_PASS:-}" ]]; then
+      openssl enc -aes-256-cbc -pbkdf2 -salt -pass env:ENV_VAULT_PASS \
+          -in "${TAR_PATH}" -out "${VAULT_PATH}"
+    else
+      openssl enc -aes-256-cbc -pbkdf2 -salt \
+          -in "${TAR_PATH}" -out "${VAULT_PATH}"
+    fi
+    ;;
+  age)
+    age -p -o "${VAULT_PATH}" "${TAR_PATH}"
+    ;;
+  gpg)
+    if [[ -n "${ENV_VAULT_PASS:-}" ]]; then
+      printf '%s' "${ENV_VAULT_PASS}" | gpg --batch --yes --symmetric \
+          --cipher-algo AES256 --passphrase-fd 0 --pinentry-mode loopback \
+          --output "${VAULT_PATH}" "${TAR_PATH}"
+    else
+      gpg --symmetric --cipher-algo AES256 --output "${VAULT_PATH}" "${TAR_PATH}"
+    fi
+    ;;
+esac
+
+# Securely remove the unencrypted tar
+rm -f "${TAR_PATH}"
+
+# ── final output ──────────────────────────────────────────────────────────────
+VAULT_SIZE=$(du -sh "${VAULT_PATH}" | cut -f1)
+
+echo ""
+echo "Vault written: ${VAULT_PATH} (${VAULT_SIZE})"
+echo "Manifest:      ${MANIFEST_PATH}"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  NEXT STEPS — 3-LOCATION BACKUP RULE"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  The encrypted vault is safe to move (secrets are encrypted)."
+echo "  Store it in at least 3 locations:"
+echo "    1. ✓ Already here: ${OUTPUT_DIR}"
+echo "    2. Copy to iCloud Drive / 1Password attachment / USB drive"
+echo "    3. Copy to a second USB or private cloud vault"
+echo ""
+echo "  Transfer to new Macs:"
+echo "    • AirDrop the .${ENC_EXT} file directly"
+echo "    • OR copy via USB drive"
+echo "    • OR store in private (non-public) cloud storage"
+echo ""
+echo "  On the new Mac, run:"
+echo "    bash restore.sh <path-to-vault.tar.${ENC_EXT}>"
+echo ""
+echo "  The passphrase is NOT stored anywhere — keep it in 1Password."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/scripts/env-vault/restore.sh

@@ -0,0 +1,149 @@
+#!/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.
+#
+# 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)
+
+set -euo pipefail
+
+# ── defaults ──────────────────────────────────────────────────────────────────
+TARGET_ROOT="${ENV_VAULT_RESTORE_ROOT:-/Users/houstongolden/Desktop/CODE_2025}"
+FORCE=false
+VAULT_FILE=""
+
+# ── parse args ─────────────────────────────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --force)  FORCE=true; shift ;;
+    --root)   TARGET_ROOT="$2"; shift 2 ;;
+    -*)       echo "Unknown flag: $1" >&2; exit 1 ;;
+    *)
+      if [[ -z "${VAULT_FILE}" ]]; then
+        VAULT_FILE="$1"
+      else
+        echo "Unexpected argument: $1" >&2
+        exit 1
+      fi
+      shift ;;
+  esac
+done
+
+if [[ -z "${VAULT_FILE}" ]]; then
+  echo "Usage: bash restore.sh [--force] [--root <path>] <vault-file>" >&2
+  echo "  vault-file: env-vault-*.tar.age | .tar.gpg | .tar.enc" >&2
+  exit 1
+fi
+
+if [[ ! -f "${VAULT_FILE}" ]]; then
+  echo "ERROR: Vault file not found: ${VAULT_FILE}" >&2
+  exit 1
+fi
+
+# ── detect encryption tool from extension ─────────────────────────────────────
+case "${VAULT_FILE}" in
+  *.tar.age) ENC_TOOL="age" ;;
+  *.tar.gpg) ENC_TOOL="gpg" ;;
+  *.tar.enc) ENC_TOOL="openssl" ;;
+  *)
+    echo "ERROR: Unrecognised vault extension. Expected .tar.age / .tar.gpg / .tar.enc" >&2
+    exit 1 ;;
+esac
+
+if ! command -v "${ENC_TOOL}" &>/dev/null && [[ "${ENC_TOOL}" != "openssl" ]]; then
+  echo "ERROR: ${ENC_TOOL} is not installed." >&2
+  exit 1
+fi
+
+echo "Encryption tool: ${ENC_TOOL}"
+echo "Vault file:      ${VAULT_FILE}"
+echo "Target root:     ${TARGET_ROOT}"
+echo ""
+
+# ── decrypt into a temp dir ────────────────────────────────────────────────────
+WORK_DIR="$(mktemp -d)"
+TAR_PATH="${WORK_DIR}/vault.tar"
+
+trap 'rm -rf "${WORK_DIR}"' EXIT
+
+echo "Decrypting vault…"
+
+case "${ENC_TOOL}" in
+  openssl)
+    if [[ -n "${ENV_VAULT_PASS:-}" ]]; then
+      openssl enc -d -aes-256-cbc -pbkdf2 -pass env:ENV_VAULT_PASS \
+          -in "${VAULT_FILE}" -out "${TAR_PATH}"
+    else
+      openssl enc -d -aes-256-cbc -pbkdf2 \
+          -in "${VAULT_FILE}" -out "${TAR_PATH}"
+    fi
+    ;;
+  age)
+    age -d -o "${TAR_PATH}" "${VAULT_FILE}"
+    ;;
+  gpg)
+    if [[ -n "${ENV_VAULT_PASS:-}" ]]; then
+      printf '%s' "${ENV_VAULT_PASS}" | gpg --batch --yes --decrypt \
+          --passphrase-fd 0 --pinentry-mode loopback \
+          --output "${TAR_PATH}" "${VAULT_FILE}"
+    else
+      gpg --output "${TAR_PATH}" --decrypt "${VAULT_FILE}"
+    fi
+    ;;
+esac
+
+echo "Decryption complete."
+echo ""
+
+# ── extract into work dir ─────────────────────────────────────────────────────
+EXTRACT_DIR="${WORK_DIR}/extracted"
+mkdir -p "${EXTRACT_DIR}"
+tar -xf "${TAR_PATH}" -C "${EXTRACT_DIR}"
+
+# ── restore each .env.local ───────────────────────────────────────────────────
+RESTORED=0
+SKIPPED=0
+BACKED_UP=0
+
+while IFS= read -r -d '' ENV_FILE; do
+  # ENV_FILE is relative to EXTRACT_DIR, e.g. ./project-name/.env.local
+  REL_PATH="${ENV_FILE#${EXTRACT_DIR}/}"   # project-name/.env.local
+  PROJECT_NAME="$(dirname "${REL_PATH}")"   # project-name
+  DEST="${TARGET_ROOT}/${PROJECT_NAME}/.env.local"
+  DEST_DIR="$(dirname "${DEST}")"
+
+  if [[ -f "${DEST}" ]]; then
+    if [[ "${FORCE}" == "true" ]]; then
+      mkdir -p "${DEST_DIR}"
+      cp "${ENV_FILE}" "${DEST}"
+      echo "  RESTORED (overwrite): ${DEST}"
+      (( RESTORED++ )) || true
+    else
+      TS="$(date -u +%Y%m%dT%H%M%SZ)"
+      BAK="${DEST}.bak.${TS}"
+      cp "${DEST}" "${BAK}"
+      cp "${ENV_FILE}" "${DEST}"
+      echo "  RESTORED (backed up old → $(basename "${BAK}")): ${DEST}"
+      (( RESTORED++ )) || true
+      (( BACKED_UP++ )) || true
+    fi
+  else
+    # Target project dir may not exist yet on a fresh machine — create it
+    mkdir -p "${DEST_DIR}"
+    cp "${ENV_FILE}" "${DEST}"
+    echo "  RESTORED (new):     ${DEST}"
+    (( RESTORED++ )) || true
+  fi
+done < <(find "${EXTRACT_DIR}" -name ".env.local" -print0)
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Restore summary"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Restored: ${RESTORED}  |  Skipped: ${SKIPPED}  |  Old files backed up: ${BACKED_UP}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Secrets are now in place. Do not print or share .env.local files."

package/scripts/skillstack-sync/README.md

@@ -0,0 +1,166 @@
+# skillstack-sync
+
+Cross-machine sync toolkit for Houston Golden's agent skill/stack setup.
+
+## What this syncs
+
+### Sync plane: Skills & Stacks (this toolkit)
+
+| What | How | Notes |
+|---|---|---|
+| `~/.agent-shared` | git push/pull to `houstongolden/agent-shared` | Canonical shared agent layer: AGENTS.md, learnings, preferences, STACK-MAP |
+| `~/.claude/scistack` | git push/pull to `Hubify-Projects/scistack` | Science skills: astrostack, hubstack, extensions |
+| 4 loose skills (see below) | rsync into agent-shared repo, then back out | Ride along in agent-shared without their own repo |
+
+**Loose skills synced via agent-shared/claude-skills/:**
+- `agent-runtime-guard`
+- `agent-stack-sync`
+- `continue`
+- `skill-governor`
+
+### What does NOT sync here
+
+| What | Why |
+|---|---|
+| `~/.claude/skills/gstack/` | Tracks upstream `garrytan/gstack` — updated via `/gstack-upgrade`, read-only to us |
+| Project files / code | Synced via their own project repos (youmd, bamfaiapp, etc.) |
+| Secrets / env vars | Use the env-vault (`cli/scripts/env-vault/`) |
+
+### Complementary sync planes
+
+- **Identity plane:** `youmd sync` (Convex ↔ local profile, memories, preferences). Automated via `com.youmd.identity-sync` daemon.
+- **Env-vault plane:** `cli/scripts/env-vault/restore.sh` for secrets (manual, invoked on new machine); also available as `youmd env restore <vault>`.
+
+---
+
+## Files
+
+```
+cli/scripts/skillstack-sync/
+├── sync.sh                         Core syncer (bash 3.2 compatible)
+├── install-daemons.sh              Installs both 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
+└── README.md                       This file
+```
+
+---
+
+## Sync logic (sync.sh)
+
+```
+1. Mirror loose skills:  ~/.claude/skills/<name>/ → ~/.agent-shared/claude-skills/<name>/
+2. Sync ~/.agent-shared:
+     a. git add -A + commit "auto-sync: <host> <timestamp>" if dirty
+     b. git pull --no-rebase --no-edit (merge)
+        → on conflict: abort merge, log LOUD warning, skip push, continue
+     c. git push
+3. Sync ~/.claude/scistack: same a/b/c sequence
+4. Reverse-mirror loose skills: ~/.agent-shared/claude-skills/<name>/ → ~/.claude/skills/<name>/
+     → backs up existing local copy to <name>.bak.<timestamp> before overwriting
+     → skips if no changes detected
+```
+
+All actions logged to `~/.youmd/logs/skillstack-sync.log`.
+
+### Flags
+
+```bash
+youmd stack sync              # live sync (all repos + loose skills)
+youmd stack sync --dry-run    # log what WOULD happen, write nothing
+
+# or run the script directly:
+./sync.sh
+./sync.sh --dry-run
+```
+
+### Env overrides
+
+```bash
+SKILLSTACK_REPOS="/path/to/repo1 /path/to/repo2"  # override repo list
+GIT_USER_NAME="Houston Golden"                      # commit author (default)
+GIT_USER_EMAIL="houston@bamf.ai"                    # commit email (default)
+```
+
+---
+
+## Daemon setup (existing machine)
+
+The preferred way is via the CLI:
+
+```bash
+youmd stack daemon install    # installs both LaunchAgents
+youmd stack daemon status     # check loaded/not-loaded
+youmd stack daemon uninstall  # remove plists from ~/Library/LaunchAgents/
+```
+
+Or run the raw script directly:
+
+```bash
+bash cli/scripts/skillstack-sync/install-daemons.sh
+```
+
+Installs two LaunchAgents that fire every 300 seconds (5 minutes):
+- `com.youmd.skillstack-sync` → runs `youmd stack sync`
+- `com.youmd.identity-sync` → runs `youmd sync`
+
+Check status:
+```bash
+youmd stack daemon status
+# or directly:
+launchctl list com.youmd.skillstack-sync
+launchctl list com.youmd.identity-sync
+```
+
+Check logs:
+```bash
+tail -f ~/.youmd/logs/skillstack-sync.log
+tail -f ~/.youmd/logs/skillstack-sync.out.log
+tail -f ~/.youmd/logs/identity-sync.out.log
+```
+
+### Uninstall daemons
+
+```bash
+youmd stack daemon uninstall
+```
+
+Or manually:
+```bash
+launchctl unload ~/Library/LaunchAgents/com.youmd.skillstack-sync.plist
+launchctl unload ~/Library/LaunchAgents/com.youmd.identity-sync.plist
+rm ~/Library/LaunchAgents/com.youmd.skillstack-sync.plist
+rm ~/Library/LaunchAgents/com.youmd.identity-sync.plist
+```
+
+---
+
+## New Mac setup
+
+```bash
+# 1. Install youmd CLI
+curl -fsSL https://you.md/install.sh | bash
+
+# 2. Clone this repo (youmd)
+git clone https://github.com/houstongolden/youmd ~/Desktop/CODE_2025/youmd
+
+# 3. Run bootstrap (clones agent-shared + scistack)
+bash ~/Desktop/CODE_2025/youmd/cli/scripts/skillstack-sync/bootstrap-new-mac.sh
+
+# 4. Restore secrets from env-vault (manual step — see env-vault/README)
+
+# 5. Activate daemons
+youmd stack daemon install
+```
+
+The bootstrap script is idempotent (safe to re-run).
+
+---
+
+## Compatibility
+
+Scripts target macOS with:
+- bash 3.2.57 (default macOS shell)
+- BSD coreutils (no GNU `mapfile`, no `mktemp --suffix`, BSD `date`/`find`/`rsync`)
+- No external tools installed beyond: `git`, `rsync`, `bash` (all stock on macOS)