youmd 0.8.2 → 0.8.6

package/scripts/env-vault/restore.sh

@@ -4,7 +4,8 @@
 # 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 [--list] [--force] [--root <target-root>] <vault-file>
+# Usage: bash restore.sh [--list] [--force] [--map-existing] [--existing-only]
+#        [--skip-agent-auth] [--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
@@ -31,15 +32,21 @@ AGENT_AUTH_MAP=(
 TARGET_ROOT="${ENV_VAULT_RESTORE_ROOT:-/Users/houstongolden/Desktop/CODE_2025}"
 FORCE=false
 LIST_ONLY=false
+MAP_EXISTING=false
+EXISTING_ONLY=false
+SKIP_AGENT_AUTH=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 ;;
+    --list)            LIST_ONLY=true; shift ;;
+    --force)           FORCE=true; shift ;;
+    --map-existing)    MAP_EXISTING=true; shift ;;
+    --existing-only)   EXISTING_ONLY=true; shift ;;
+    --skip-agent-auth) SKIP_AGENT_AUTH=true; shift ;;
+    --root)            TARGET_ROOT="$2"; shift 2 ;;
+    -*)                echo "Unknown flag: $1" >&2; exit 1 ;;
     *)
       if [[ -z "${VAULT_FILE}" ]]; then
         VAULT_FILE="$1"
@@ -52,7 +59,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 if [[ -z "${VAULT_FILE}" ]]; then
-  echo "Usage: bash restore.sh [--list] [--force] [--root <path>] <vault-file>" >&2
+  echo "Usage: bash restore.sh [--list] [--force] [--map-existing] [--existing-only] [--skip-agent-auth] [--root <path>] <vault-file>" >&2
   echo "  vault-file: env-vault-*.tar.age | .tar.gpg | .tar.enc" >&2
   exit 1
 fi
@@ -80,8 +87,53 @@ fi
 echo "Encryption tool: ${ENC_TOOL}"
 echo "Vault file:      ${VAULT_FILE}"
 echo "Target root:     ${TARGET_ROOT}"
+echo "Project mapping: map-existing=${MAP_EXISTING} existing-only=${EXISTING_ONLY}"
+echo "Agent auth:      $([[ "${SKIP_AGENT_AUTH}" == "true" ]] && echo "skip" || echo "restore")"
 echo ""
 
+normalize_project_name() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]//g'
+}
+
+map_project_name() {
+  local archive_name="$1"
+  local exact_dir="${TARGET_ROOT}/${archive_name}"
+  if [[ "${MAP_EXISTING}" != "true" ]]; then
+    printf '%s\n' "${archive_name}"
+    return 0
+  fi
+  if [[ -d "${exact_dir}" ]]; then
+    printf '%s\n' "${archive_name}"
+    return 0
+  fi
+
+  local wanted
+  wanted="$(normalize_project_name "${archive_name}")"
+  local matches=()
+  local candidate
+  while IFS= read -r -d '' candidate; do
+    local base
+    base="$(basename "${candidate}")"
+    if [[ "$(normalize_project_name "${base}")" == "${wanted}" ]]; then
+      matches+=("${base}")
+    fi
+  done < <(find "${TARGET_ROOT}" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null || true)
+
+  if [[ "${#matches[@]}" -eq 1 ]]; then
+    printf '%s\n' "${matches[0]}"
+    return 0
+  fi
+  if [[ "${#matches[@]}" -gt 1 ]]; then
+    echo "WARN: multiple existing dirs match vault project '${archive_name}': ${matches[*]} — skipping" >&2
+    return 1
+  fi
+  if [[ "${EXISTING_ONLY}" == "true" ]]; then
+    echo "WARN: no existing dir for vault project '${archive_name}' under ${TARGET_ROOT} — skipping" >&2
+    return 1
+  fi
+  printf '%s\n' "${archive_name}"
+}
+
 # ── decrypt into a temp dir ────────────────────────────────────────────────────
 WORK_DIR="$(mktemp -d)"
 TAR_PATH="${WORK_DIR}/vault.tar"
@@ -130,18 +182,30 @@ if [[ "${LIST_ONLY}" == "true" ]]; then
   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}")"
+    ARCHIVE_PROJECT_NAME="$(dirname "${REL_PATH}")"
+    if ! PROJECT_NAME="$(map_project_name "${ARCHIVE_PROJECT_NAME}")"; then
+      echo "  env: ${ARCHIVE_PROJECT_NAME}/.env.local -> SKIPPED (no safe target)"
+      (( ENV_COUNT++ )) || true
+      continue
+    fi
     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}])"
+    if [[ "${ARCHIVE_PROJECT_NAME}" == "${PROJECT_NAME}" ]]; then
+      echo "  env: ${PROJECT_NAME}/.env.local -> ${DEST} (${VAR_COUNT} variable(s) [${VAR_NAMES}])"
+    else
+      echo "  env: ${ARCHIVE_PROJECT_NAME}/.env.local -> ${DEST} (${VAR_COUNT} variable(s) [${VAR_NAMES}])"
+    fi
     (( 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
+  if [[ "${SKIP_AGENT_AUTH}" == "true" ]]; then
+    echo "    skipped by --skip-agent-auth"
+  else
+    for ENTRY in "${AGENT_AUTH_MAP[@]}"; do
     ARCHIVE_NAME="${ENTRY%%:*}"
     DEST_PATH="${ENTRY##*:}"
     SRC_FILE="${AGENT_AUTH_SRC}/${ARCHIVE_NAME}"
@@ -153,7 +217,8 @@ if [[ "${LIST_ONLY}" == "true" ]]; then
       echo "    missing: agent-auth/${ARCHIVE_NAME}"
       (( AGENT_MISSING++ )) || true
     fi
-  done
+    done
+  fi
 
   echo ""
   echo "List summary: ${ENV_COUNT} .env.local file(s), ${AGENT_PRESENT} agent-auth file(s) present, ${AGENT_MISSING} agent-auth file(s) missing."
@@ -169,7 +234,12 @@ 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
+  ARCHIVE_PROJECT_NAME="$(dirname "${REL_PATH}")"   # project-name
+  if ! PROJECT_NAME="$(map_project_name "${ARCHIVE_PROJECT_NAME}")"; then
+    echo "  SKIPPED (no existing mapped target): ${ARCHIVE_PROJECT_NAME}/.env.local"
+    (( SKIPPED++ )) || true
+    continue
+  fi
   DEST="${TARGET_ROOT}/${PROJECT_NAME}/.env.local"
   DEST_DIR="$(dirname "${DEST}")"
 
@@ -204,7 +274,10 @@ AGENT_BACKED_UP=0
 
 AGENT_AUTH_SRC="${EXTRACT_DIR}/agent-auth"
 
-if [[ -d "${AGENT_AUTH_SRC}" ]]; then
+if [[ "${SKIP_AGENT_AUTH}" == "true" ]]; then
+  echo "Skipping agent-auth restore because --skip-agent-auth was provided."
+  echo ""
+elif [[ -d "${AGENT_AUTH_SRC}" ]]; then
   echo "Restoring agent-auth files…"
   for ENTRY in "${AGENT_AUTH_MAP[@]}"; do
     ARCHIVE_NAME="${ENTRY%%:*}"

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 --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.
+- **Realtime identity/project plane:** `youmd sync --live --daemon` subscribes to Convex websocket updates, mints only a short-lived sync session token, materializes identity files and installed You.md skills locally, and triggers bounded shared stack/project-context syncs. It never prints or returns raw `.env.local` values.
+- **Identity repair plane:** `youmd sync --daemon` (Convex ↔ local profile, memories, preferences). Automated via `com.youmd.identity-sync` daemon as a timer-based fallback. 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>`.
 
@@ -41,6 +42,7 @@ cli/scripts/skillstack-sync/
 ├── sync.sh                         Core syncer (bash 3.2 compatible)
 ├── install-daemons.sh              Installs all resident LaunchAgents
 ├── bootstrap-new-mac.sh            New machine setup script
+├── com.youmd.realtime-sync.plist   LaunchAgent: runs `youmd sync --live --daemon` as a resident websocket syncer
 ├── com.youmd.skillstack-sync.plist LaunchAgent: runs `youmd stack 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
@@ -103,7 +105,8 @@ Or run the raw script directly:
 bash cli/scripts/skillstack-sync/install-daemons.sh
 ```
 
-Installs three LaunchAgents:
+Installs four LaunchAgents:
+- `com.youmd.realtime-sync` → runs `youmd sync --live --daemon`
 - `com.youmd.skillstack-sync` → runs `youmd stack sync`
 - `com.youmd.identity-sync` → runs `youmd sync --daemon`
 - `com.youmd.context-sync` → runs `youmd stack context-sync`
@@ -113,6 +116,7 @@ Check status:
 youmd stack daemon status
 # or directly:
 launchctl list com.youmd.skillstack-sync
+launchctl list com.youmd.realtime-sync
 launchctl list com.youmd.identity-sync
 launchctl list com.youmd.context-sync
 ```
@@ -145,19 +149,33 @@ rm ~/Library/LaunchAgents/com.youmd.context-sync.plist
 
 ## New Mac setup
 
+Preferred path: open the You.md Machine tab on an authenticated source computer,
+copy the fresh-machine Claude/Codex setup prompt, and paste it into Claude Code
+or Codex on the new Mac. That generated prompt checks/install Homebrew, Node 22,
+GitHub CLI, bun, and pnpm; authenticates You.md; requires GitHub auth before
+private clones; clones only setup-eligible active projects into
+`~/Desktop/CODE_YOU`; restores env files with `--map-existing --existing-only
+--skip-agent-auth`; and installs resident daemons.
+
+Fallback manual path:
+
 ```bash
 # 1. Install youmd CLI
 curl -fsSL https://you.md/install.sh | bash
 
-# 2. Clone this repo (youmd)
+# 2. Authenticate GitHub before private stack/project clones
+gh auth login -h github.com -p https -s repo
+
+# 3. Clone this repo (youmd)
 git clone https://github.com/houstongolden/youmd ~/Desktop/CODE_2025/youmd
 
-# 3. Run bootstrap (clones agent-shared + scistack)
+# 4. 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. Restore project env files from env-vault (manual step — see env-vault/README)
+youmd env restore <vault> --root ~/Desktop/CODE_YOU --map-existing --existing-only --skip-agent-auth
 
-# 5. Activate daemons
+# 6. Activate daemons
 youmd stack daemon install
 ```
 

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

@@ -10,6 +10,7 @@
 # Usage: bash bootstrap-new-mac.sh
 
 set -euo pipefail
+export PATH="${HOME}/.youmd/bin:${HOME}/.youmd/npm-global/bin:/opt/homebrew/opt/node@22/bin:/usr/local/opt/node@22/bin:/opt/homebrew/bin:/usr/local/bin:${PATH}"
 
 AGENT_SHARED="${HOME}/.agent-shared"
 SCISTACK="${HOME}/.claude/scistack"
@@ -33,6 +34,34 @@ warn() {
   echo "     WARN: $*"
 }
 
+ensure_github_auth() {
+  if ! command -v gh >/dev/null 2>&1; then
+    warn "GitHub CLI is missing. Install it with Homebrew first: brew install gh"
+    return 1
+  fi
+
+  if gh auth status >/dev/null 2>&1; then
+    info "GitHub auth ready."
+    return 0
+  fi
+
+  warn "GitHub auth is required before private skill/stack repos can clone."
+  if [ -t 0 ]; then
+    gh auth login -h github.com -p https -s repo || true
+  fi
+
+  if gh auth status >/dev/null 2>&1; then
+    info "GitHub auth ready."
+    return 0
+  fi
+
+  warn "GitHub auth still is not complete."
+  warn "Open a normal Terminal and run:"
+  warn "  $(command -v gh || echo gh) auth login -h github.com -p https -s repo"
+  warn "Then rerun: youmd machine setup"
+  return 1
+}
+
 # ---------------------------------------------------------------------------
 step "1. Install youmd CLI"
 # ---------------------------------------------------------------------------
@@ -47,6 +76,8 @@ fi
 # ---------------------------------------------------------------------------
 step "2. Clone agent-shared repo → ${AGENT_SHARED}"
 # ---------------------------------------------------------------------------
+ensure_github_auth
+
 if [ -d "${AGENT_SHARED}/.git" ]; then
   info "Already present: ${AGENT_SHARED} — skipping clone."
 else

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

@@ -0,0 +1,35 @@
+<?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.realtime-sync</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/zsh</string>
+        <string>-lc</string>
+        <string>youmd sync --live --daemon</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.youmd/logs/realtime-sync.out.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.youmd/logs/realtime-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/install-daemons.sh

@@ -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 com.youmd.context-sync"
+PLISTS="com.youmd.realtime-sync com.youmd.skillstack-sync com.youmd.identity-sync com.youmd.context-sync"
 
 echo "==> Creating log directory: ${LOG_DIR}"
 mkdir -p "${LOG_DIR}"
@@ -58,6 +58,8 @@ echo "================================================================"
 echo "Resident You.md daemons installed and running."
 echo ""
 echo "Log files:"
+echo "  ${LOG_DIR}/realtime-sync.out.log   (Convex websocket sync stdout)"
+echo "  ${LOG_DIR}/realtime-sync.err.log   (Convex websocket sync stderr)"
 echo "  ${LOG_DIR}/skillstack-sync.log      (combined sync log)"
 echo "  ${LOG_DIR}/skillstack-sync.out.log  (daemon stdout)"
 echo "  ${LOG_DIR}/skillstack-sync.err.log  (daemon stderr)"
@@ -68,6 +70,7 @@ 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.realtime-sync"
 echo "  launchctl list com.youmd.skillstack-sync"
 echo "  launchctl list com.youmd.identity-sync"
 echo "  launchctl list com.youmd.context-sync"

package/skills/machine-bootstrap.md

@@ -34,12 +34,14 @@ You.md is the brain. The new machine should become a runnable local agent workst
    for Claude Code or Codex on the new machine, generate it first:
 
    ```bash
-   youmd machine prompt --root ~/Desktop/CODE_YOU --days 90
+   youmd machine prompt --root ~/Desktop/CODE_YOU --days 30 --limit 80 --require-env-vault
    ```
 
    If the web dashboard minted a scoped bootstrap key, the generated prompt may
    include `YOUMD_API_KEY`. Treat that prompt as secret-bearing local setup
    material and do not paste it into public chats, tickets, or docs.
+   Fresh-machine bootstrap keys must include the `vault` scope so the trusted
+   device can pull encrypted Secret Vault snapshots after login.
    For bounded proof runs on a clean local root, add
    `--max-clone-projects 2` or set `YOUMD_MAX_CLONE_PROJECTS=2`; omit that cap
    on the real new machine.
@@ -70,31 +72,40 @@ You.md is the brain. The new machine should become a runnable local agent workst
 
 6. Hydrate the portfolio graph from You.md/GitHub records before cloning, then
    preview the graph-backed setup plan before creating the desktop code workspace
-   and syncing active projects:
+   and syncing truly active 30-day projects first:
+
+   ```bash
+   youmd project portfolio-hydrate --root ~/Desktop/CODE_YOU --days 30 --limit 80
+   youmd machine projects --root ~/Desktop/CODE_YOU --days 30 --recent-only --dry-run
+   youmd machine projects --root ~/Desktop/CODE_YOU --days 30 --recent-only
+   ```
+
+7. Ask whether Houston wants to expand the workspace to all active projects
+   from the last 90 days before calling the full project clone set complete:
 
    ```bash
    youmd project portfolio-hydrate --root ~/Desktop/CODE_YOU --days 90 --limit 80
-   youmd machine projects --root ~/Desktop/CODE_YOU --days 90 --dry-run
-   youmd machine projects --root ~/Desktop/CODE_YOU --days 90
+   youmd machine projects --root ~/Desktop/CODE_YOU --days 90 --recent-only --dry-run
+   youmd machine projects --root ~/Desktop/CODE_YOU --days 90 --recent-only
    ```
 
-7. If GitHub auth is missing, help the user log in and rerun only the project
+8. If GitHub auth is missing, help the user log in and rerun only the project
    clone step:
 
    ```bash
    gh auth login
-   youmd machine projects --root ~/Desktop/CODE_YOU --days 90
+   youmd machine projects --root ~/Desktop/CODE_YOU --days 30 --recent-only
    ```
 
-8. After projects are cloned and any encrypted env vault is restored, hydrate the
+9. After projects are cloned and any encrypted env vault is restored, hydrate the
    portfolio graph again so local README, project-context, git, PR, and env-key
    evidence becomes visible to future agents:
 
    ```bash
-   youmd project portfolio-hydrate --root ~/Desktop/CODE_YOU --days 90 --limit 80
+   youmd project portfolio-hydrate --root ~/Desktop/CODE_YOU --days 30 --limit 80
    ```
 
-9. Run the secret-safe readiness audit and sync the proof summary:
+10. Run the secret-safe readiness audit and sync the proof summary:
 
    ```bash
    youmd machine verify --root ~/Desktop/CODE_YOU --max-projects 80 --write-report --sync-report
@@ -107,7 +118,7 @@ You.md is the brain. The new machine should become a runnable local agent workst
    summary to the You.md machine dashboard. It does not read secret values,
    upload raw logs, or launch every dev server.
 
-10. Only when Houston explicitly wants deeper local proof or the clean host has
+11. Only when Houston explicitly wants deeper local proof or the clean host has
     enough time/CPU, run bounded package checks and dev-server probes:
 
    ```bash
@@ -119,11 +130,46 @@ You.md is the brain. The new machine should become a runnable local agent workst
    and dev-server probes are capped by default; tune with
    `--max-install-projects`, `--max-server-projects`, and timeout flags.
 
+## Behind-the-Scenes Agent Operation
+
+- Use the You.md CLI and You Agent yourself before asking Houston to do manual
+  work. Prefer deterministic commands for setup and proof:
+  `youmd status`, `youmd whoami`, `youmd pull`, `youmd sync`,
+  `youmd machine prompt`, `youmd machine setup`,
+  `youmd skill install all`, `youmd skill sync`,
+  `youmd env vault list`, `youmd env vault pull`,
+  `youmd project portfolio-hydrate`, `youmd machine verify`,
+  `youmd agent status`, and `youmd agent inbox`.
+- Report setup milestones to Houston's other trusted Macs with the realtime
+  agent bus instead of relying on clipboard/manual status relays:
+
+  ```bash
+  youmd agent send --channel machine-sync --kind status "Mac mini completed identity + skill sync"
+  ```
+
+  This writes through Convex realtime and the receiving daemon materializes it
+  into `~/.youmd/agent-bus/inbox.json` without reading or exposing `.env.local`
+  values.
+- Use `you` / `youmd chat` when you need the You Agent to synthesize context,
+  route a natural-language request, or produce the setup artifact, then turn the
+  result into concrete shell actions.
+- Do not stop to ask "what next?" after each setup phase. Continue through the
+  command, verify the result, and report concise proof.
+- Interrupt Houston only for true human-gated steps: GitHub browser auth,
+  source-Mac Secret Vault share/passphrase entry if no trusted-device envelope
+  exists yet, npm OTP, OS permissions, or the explicit 90-day project expansion
+  choice.
+- If the installed CLI is stale, run the curl installer/update path first, then
+  retry the You.md command. Tell Houston when npm publish is needed for
+  `npx youmd@latest` or npm fallback installs.
+
 ## Project Bootstrap Rules
 
 - Use repo directory names from GitHub URLs. `https://github.com/houstongolden/foldermd` becomes `foldermd`.
-- Default to projects active in the last 90 days plus projects marked active/current in You.md.
-- Ask before including older, archived, paused, or dormant projects.
+- Default to projects active in the last 30 days and marked active plus Top
+  Priority/Focusing in You.md. Ask before expanding to the 90-day active set.
+- Ask before including older, archived, paused, inactive, on-ice, abandoned,
+  killed, dormant, or unsorted projects.
 - Create the workspace root on the Desktop if it is missing. `CODE_YOU` is the default fresh-machine root.
 - Use the You.md Portfolio Graph as the strategic source of truth, then merge
   authenticated GitHub recent-repo data and local bundle project records so repo
@@ -133,7 +179,9 @@ You.md is the brain. The new machine should become a runnable local agent workst
   local bundle plus authenticated GitHub scan and say so.
 - Clone with `gh repo clone owner/repo <target>` when `gh` is authenticated; otherwise fall back to `git clone`.
 - Skip non-empty directories instead of overwriting them.
-- Never print secrets. If `.env.local` files are needed, use the shared encrypted env backup/restore path or a password manager.
+- Never print secrets. If `.env.local` files are needed, use You.md Secret Vault
+  or the shared encrypted env backup/restore path. Never paste raw env values
+  into chat.
 - After cloning, initialize missing per-repo agent context with `youmd skill init-project` from inside that repo.
 
 ## Secret-Safe Env Transfer
@@ -146,18 +194,65 @@ Audit local project env coverage before backup:
 youmd env backup --root ~/Desktop/CODE_2025 --preflight
 ```
 
-Create an encrypted archive from the old machine in an interactive macOS terminal:
+Primary path: from the old/source machine, create an encrypted archive and push
+only the ciphertext plus safe manifest metadata to You.md Secret Vault:
+
+```bash
+youmd env vault push --root ~/Desktop/CODE_2025 --out ~/Desktop/youmd-env-vault
+youmd env vault list
+```
+
+On the new machine, register its local Secret Vault device key. The private key
+stays under `~/.youmd/secret-vault/devices/`; only the public key is synced:
+
+```bash
+youmd env vault device-register
+```
+
+Back on the old/source machine, share local decrypt access to trusted devices.
+This stores per-device encrypted passphrase envelopes; it does not upload raw env
+values:
+
+```bash
+youmd env vault share
+```
+
+On the new machine, pull the latest encrypted account snapshot and restore into
+already-cloned project directories without clobbering local agent auth:
+
+```bash
+youmd env vault pull --restore --root ~/Desktop/CODE_YOU --map-existing --existing-only --skip-agent-auth
+```
+
+If `pull --restore` says no trusted-device envelope exists for this Mac, do not
+ask Houston for raw secrets. Confirm `device-register` ran on the new Mac, run
+`youmd env vault share` on the source Mac, then rerun `pull --restore`.
+
+Fallback path: create an encrypted archive from the old machine in an
+interactive macOS terminal and transfer the encrypted file by iCloud, AirDrop,
+USB, or private password-manager attachment:
 
 ```bash
 open ~/.agent-shared/bin/env-backup-interactive.command
+youmd env backup --root ~/Desktop/CODE_2025 --out ~/Desktop/youmd-env-vault
 ```
 
 On the new machine, list the encrypted archive by path only before restore:
 
 ```bash
 ~/.agent-shared/bin/env-secure-restore.sh --archive ~/Desktop/env-local-backup.tar.gz.gpg --list
-youmd env restore ~/Desktop/env-local-backup.tar.gz.gpg --root ~/Desktop/CODE_YOU --list
-youmd env restore ~/Desktop/env-local-backup.tar.gz.gpg --root ~/Desktop/CODE_YOU
+youmd env restore ~/Desktop/env-local-backup.tar.gz.gpg --root ~/Desktop/CODE_YOU --list --map-existing --existing-only --skip-agent-auth
+youmd env restore ~/Desktop/env-local-backup.tar.gz.gpg --root ~/Desktop/CODE_YOU --map-existing --existing-only --skip-agent-auth
+```
+
+If a headless agent still cannot decrypt after device sharing, then and only then
+use the macOS Keychain fallback for the env-vault passphrase. Input is silent and
+the value is not printed:
+
+```bash
+read -rs "PW?You.md vault passphrase: " && \
+security add-generic-password -a "$USER" -s youmd-env-vault -w "$PW" -U && \
+unset PW && echo "stored in Keychain"
 ```
 
 ## Useful Variants
@@ -165,7 +260,7 @@ youmd env restore ~/Desktop/env-local-backup.tar.gz.gpg --root ~/Desktop/CODE_YO
 Dry-run the project layout:
 
 ```bash
-youmd machine projects --root ~/Desktop/CODE_YOU --days 90 --dry-run
+youmd machine projects --root ~/Desktop/CODE_YOU --days 30 --recent-only --dry-run
 ```
 
 Create directories only, without cloning:
@@ -201,13 +296,13 @@ youmd machine projects --root ~/Desktop/CODE_YOU --yes
 Generate the copy/paste prompt for a new Claude Code or Codex terminal:
 
 ```bash
-youmd machine prompt --root ~/Desktop/CODE_YOU --days 90 --limit 80
+youmd machine prompt --root ~/Desktop/CODE_YOU --days 30 --limit 80 --require-env-vault
 ```
 
 Generate the same prompt but cap clones for a clean-host proof run:
 
 ```bash
-youmd machine prompt --root /tmp/youmd-clean-host-CODE_YOU --days 90 --limit 80 --max-clone-projects 2
+youmd machine prompt --root /tmp/youmd-clean-host-CODE_YOU --days 30 --limit 80 --max-clone-projects 2 --require-env-vault
 ```
 
 Fetch the secret-safe project graph directly: