youmd 0.8.2 → 0.8.5

package/dist/lib/realtime-sync.d.ts

@@ -0,0 +1,128 @@
+export type RealtimeSyncHead = {
+    schemaVersion?: string;
+    serverNow?: number;
+    sessionExpiresAt?: number;
+    user?: {
+        username?: string;
+        plan?: string;
+    };
+    identity?: {
+        latestVersion?: number | null;
+        latestHash?: string | null;
+        publishedVersion?: number | null;
+        publishedHash?: string | null;
+        latestCreatedAt?: number | null;
+        latestPublishedAt?: number | null;
+    };
+    skills?: {
+        installedCount?: number;
+        latestInstalledAt?: number | null;
+        names?: string[];
+    };
+    portfolio?: {
+        updatedAt?: number | null;
+        projects?: number;
+        activeFocusedProjects?: number;
+        apiSurfaces?: number;
+        dependencyEdges?: number;
+        reusablePatterns?: number;
+        activities?: number;
+        providerAccounts?: number;
+        tasks?: number;
+        brainDumps?: number;
+        machineProofs?: number;
+    };
+    repoMirror?: {
+        repoFullName?: string | null;
+        commitSha?: string | null;
+        fileCount?: number;
+        totalBytes?: number;
+        truncated?: boolean;
+        syncedAt?: number;
+    } | null;
+    github?: {
+        repoFullName?: string | null;
+        lastSyncedAt?: number | null;
+        lastPushedCommitSha?: string | null;
+        mirrorStale?: boolean;
+        lastPushErrorAt?: number | null;
+    } | null;
+    encryptedEnvVault?: {
+        status?: "ready" | "missing" | "scope-missing" | string;
+        flow?: string;
+        available?: boolean;
+        snapshotCount?: number;
+        id?: string | null;
+        label?: string | null;
+        createdAt?: number | null;
+        fileName?: string | null;
+        contentType?: string | null;
+        encryptionTool?: string | null;
+        extension?: string | null;
+        formatVersion?: number | null;
+        sizeBytes?: number | null;
+        projectCount?: number | null;
+        variableCount?: number | null;
+        sha256?: string | null;
+        manifestSha256?: string | null;
+        agentAuthIncluded?: boolean;
+        sourceHost?: string | null;
+        sourceRoot?: string | null;
+        restoreMode?: string;
+        scope?: string;
+        secretValuesExposed?: false;
+    };
+};
+export declare const REALTIME_SYNC_STATUS_PATH: string;
+export type RealtimeSecretVaultStatus = {
+    state: "ready" | "missing" | "scope-missing" | "unknown";
+    flow: "account-backed-encrypted-snapshot";
+    available: boolean;
+    snapshotCount: number;
+    summary: string;
+    latestSnapshot?: {
+        id?: string | null;
+        label?: string | null;
+        fileName?: string | null;
+        createdAt?: number | null;
+        sizeBytes?: number | null;
+        projectCount?: number | null;
+        variableCount?: number | null;
+        sha256?: string | null;
+        sha256Short?: string | null;
+        manifestSha256?: string | null;
+        encryptionTool?: string | null;
+        extension?: string | null;
+        formatVersion?: number | null;
+        agentAuthIncluded?: boolean;
+        sourceHost?: string | null;
+        sourceRoot?: string | null;
+    };
+    pullCommand: string;
+    restoreCommand: string;
+    secretValuesExposed: false;
+};
+export type RealtimeSyncStatusFile = {
+    schemaVersion: "you-md/realtime-sync-daemon-status/v1";
+    generatedAt: number;
+    summary: string;
+    user?: RealtimeSyncHead["user"];
+    identity?: RealtimeSyncHead["identity"];
+    skills?: {
+        installedCount?: number;
+        latestInstalledAt?: number | null;
+    };
+    portfolio?: RealtimeSyncHead["portfolio"];
+    repoMirror?: RealtimeSyncHead["repoMirror"];
+    github?: RealtimeSyncHead["github"];
+    secretVault: RealtimeSecretVaultStatus;
+    secretValuesExposed: false;
+};
+export declare function describeRealtimeSecretVault(head: RealtimeSyncHead | null | undefined): RealtimeSecretVaultStatus;
+export declare function realtimeSyncHeadSignature(head: RealtimeSyncHead | null | undefined): string;
+export declare function summarizeRealtimeSyncHead(head: RealtimeSyncHead): string;
+export declare function buildRealtimeSyncStatusFile(head: RealtimeSyncHead): RealtimeSyncStatusFile;
+export declare function writeRealtimeSyncStatusFile(head: RealtimeSyncHead): void;
+export declare function readRealtimeSyncStatusFile(): RealtimeSyncStatusFile | null;
+export declare function shouldRunBoundedSync(lastRunAt: number, now: number, minIntervalMs: number): boolean;
+//# sourceMappingURL=realtime-sync.d.ts.map

package/dist/lib/realtime-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-sync.d.ts","sourceRoot":"","sources":["../../src/lib/realtime-sync.ts"],"names":[],"mappings":"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"}

package/dist/lib/realtime-sync.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REALTIME_SYNC_STATUS_PATH = void 0;
+exports.describeRealtimeSecretVault = describeRealtimeSecretVault;
+exports.realtimeSyncHeadSignature = realtimeSyncHeadSignature;
+exports.summarizeRealtimeSyncHead = summarizeRealtimeSyncHead;
+exports.buildRealtimeSyncStatusFile = buildRealtimeSyncStatusFile;
+exports.writeRealtimeSyncStatusFile = writeRealtimeSyncStatusFile;
+exports.readRealtimeSyncStatusFile = readRealtimeSyncStatusFile;
+exports.shouldRunBoundedSync = shouldRunBoundedSync;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+exports.REALTIME_SYNC_STATUS_PATH = path.join(os.homedir(), ".youmd", "realtime-sync-status.json");
+function shortSha(value) {
+    if (!value)
+        return null;
+    return value.length <= 16 ? value : `${value.slice(0, 12)}...${value.slice(-8)}`;
+}
+function describeRealtimeSecretVault(head) {
+    const vault = head?.encryptedEnvVault;
+    const state = vault?.status === "ready"
+        ? "ready"
+        : vault?.status === "scope-missing" || vault?.scope === "vault-not-granted"
+            ? "scope-missing"
+            : vault
+                ? "missing"
+                : "unknown";
+    const pullCommand = "youmd env vault pull --out ~/.youmd/secret-vault";
+    const restoreCommand = "youmd env vault pull --restore --root ~/Desktop/CODE_YOU --map-existing --existing-only --skip-agent-auth";
+    if (state === "ready") {
+        const projects = vault?.projectCount ?? 0;
+        const vars = vault?.variableCount ?? 0;
+        const source = vault?.sourceHost ? ` from ${vault.sourceHost}` : "";
+        const hash = shortSha(vault?.sha256);
+        return {
+            state,
+            flow: "account-backed-encrypted-snapshot",
+            available: true,
+            snapshotCount: vault?.snapshotCount ?? 1,
+            summary: `Secret Vault ready: ${projects} projects / ${vars} vars${source}${hash ? ` / ${hash}` : ""}`,
+            latestSnapshot: {
+                id: vault?.id ?? null,
+                label: vault?.label ?? null,
+                fileName: vault?.fileName ?? null,
+                createdAt: vault?.createdAt ?? null,
+                sizeBytes: vault?.sizeBytes ?? null,
+                projectCount: vault?.projectCount ?? null,
+                variableCount: vault?.variableCount ?? null,
+                sha256: vault?.sha256 ?? null,
+                sha256Short: hash,
+                manifestSha256: vault?.manifestSha256 ?? null,
+                encryptionTool: vault?.encryptionTool ?? null,
+                extension: vault?.extension ?? null,
+                formatVersion: vault?.formatVersion ?? null,
+                agentAuthIncluded: vault?.agentAuthIncluded === true,
+                sourceHost: vault?.sourceHost ?? null,
+                sourceRoot: vault?.sourceRoot ?? null,
+            },
+            pullCommand,
+            restoreCommand,
+            secretValuesExposed: false,
+        };
+    }
+    if (state === "scope-missing") {
+        return {
+            state,
+            flow: "account-backed-encrypted-snapshot",
+            available: false,
+            snapshotCount: 0,
+            summary: "Secret Vault unknown: current realtime key lacks vault scope",
+            pullCommand,
+            restoreCommand,
+            secretValuesExposed: false,
+        };
+    }
+    if (state === "missing") {
+        return {
+            state,
+            flow: "account-backed-encrypted-snapshot",
+            available: false,
+            snapshotCount: vault?.snapshotCount ?? 0,
+            summary: "Secret Vault missing: upload encrypted snapshot from the source Mac with `youmd env vault push`",
+            pullCommand,
+            restoreCommand,
+            secretValuesExposed: false,
+        };
+    }
+    return {
+        state,
+        flow: "account-backed-encrypted-snapshot",
+        available: false,
+        snapshotCount: 0,
+        summary: "Secret Vault not observed yet: realtime daemon has not received a vault-scoped sync head",
+        pullCommand,
+        restoreCommand,
+        secretValuesExposed: false,
+    };
+}
+function realtimeSyncHeadSignature(head) {
+    if (!head)
+        return "none";
+    return JSON.stringify({
+        identity: {
+            latestVersion: head.identity?.latestVersion ?? null,
+            latestHash: head.identity?.latestHash ?? null,
+            publishedVersion: head.identity?.publishedVersion ?? null,
+            publishedHash: head.identity?.publishedHash ?? null,
+        },
+        skills: {
+            installedCount: head.skills?.installedCount ?? 0,
+            latestInstalledAt: head.skills?.latestInstalledAt ?? null,
+            names: head.skills?.names ?? [],
+        },
+        portfolio: head.portfolio ?? null,
+        repoMirror: head.repoMirror ?? null,
+        github: head.github ?? null,
+        encryptedEnvVault: {
+            status: head.encryptedEnvVault?.status ?? null,
+            available: head.encryptedEnvVault?.available ?? false,
+            snapshotCount: head.encryptedEnvVault?.snapshotCount ?? 0,
+            id: head.encryptedEnvVault?.id ?? null,
+            createdAt: head.encryptedEnvVault?.createdAt ?? null,
+            fileName: head.encryptedEnvVault?.fileName ?? null,
+            sha256: head.encryptedEnvVault?.sha256 ?? null,
+            manifestSha256: head.encryptedEnvVault?.manifestSha256 ?? null,
+            projectCount: head.encryptedEnvVault?.projectCount ?? null,
+            variableCount: head.encryptedEnvVault?.variableCount ?? null,
+            sourceHost: head.encryptedEnvVault?.sourceHost ?? null,
+            sourceRoot: head.encryptedEnvVault?.sourceRoot ?? null,
+        },
+    });
+}
+function summarizeRealtimeSyncHead(head) {
+    const bundle = head.identity?.latestVersion
+        ? `bundle v${head.identity.latestVersion}`
+        : "bundle unknown";
+    const skills = `${head.skills?.installedCount ?? 0} skills`;
+    const projects = `${head.portfolio?.projects ?? 0} projects`;
+    const tasks = `${head.portfolio?.tasks ?? 0} tasks`;
+    const vault = describeRealtimeSecretVault(head).summary;
+    return `${bundle}, ${skills}, ${projects}, ${tasks}, ${vault}`;
+}
+function buildRealtimeSyncStatusFile(head) {
+    return {
+        schemaVersion: "you-md/realtime-sync-daemon-status/v1",
+        generatedAt: Date.now(),
+        summary: summarizeRealtimeSyncHead(head),
+        user: head.user,
+        identity: head.identity,
+        skills: {
+            installedCount: head.skills?.installedCount,
+            latestInstalledAt: head.skills?.latestInstalledAt ?? null,
+        },
+        portfolio: head.portfolio,
+        repoMirror: head.repoMirror,
+        github: head.github,
+        secretVault: describeRealtimeSecretVault(head),
+        secretValuesExposed: false,
+    };
+}
+function writeRealtimeSyncStatusFile(head) {
+    fs.mkdirSync(path.dirname(exports.REALTIME_SYNC_STATUS_PATH), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(exports.REALTIME_SYNC_STATUS_PATH, JSON.stringify(buildRealtimeSyncStatusFile(head), null, 2), { mode: 0o600 });
+}
+function readRealtimeSyncStatusFile() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(exports.REALTIME_SYNC_STATUS_PATH, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        if (parsed.secretValuesExposed !== false)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function shouldRunBoundedSync(lastRunAt, now, minIntervalMs) {
+    return lastRunAt === 0 || now - lastRunAt >= minIntervalMs;
+}
+//# sourceMappingURL=realtime-sync.js.map

package/dist/lib/realtime-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-sync.js","sourceRoot":"","sources":["../../src/lib/realtime-sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "youmd",
-  "version": "0.8.2",
+  "version": "0.8.5",
   "description": "Identity context protocol for the agent internet — an MCP where the context is you. CLI for the You.md platform.",
   "bin": {
     "you": "dist/you.js",
@@ -45,6 +45,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^4.1.2",
     "commander": "^12.1.0",
+    "convex": "1.33.1",
     "gray-matter": "^4.0.3",
     "jimp": "^0.22.12",
     "js-yaml": "^4.1.1",

package/scripts/env-vault/README.md

@@ -58,6 +58,10 @@ Do NOT transfer via unencrypted email or public Slack.
 youmd env restore /path/to/env-vault-<date>.tar.<ext> --list
 youmd env restore /path/to/env-vault-<date>.tar.<ext>
 
+# Fresh-machine restore after repos have been cloned into CODE_YOU:
+youmd env restore /path/to/env-vault-<date>.tar.<ext> --root ~/Desktop/CODE_YOU --list --map-existing --existing-only --skip-agent-auth
+youmd env restore /path/to/env-vault-<date>.tar.<ext> --root ~/Desktop/CODE_YOU --map-existing --existing-only --skip-agent-auth
+
 # If files already exist on the new Mac:
 youmd env restore --force /path/to/env-vault-<date>.tar.<ext>
 
@@ -70,6 +74,9 @@ The script:
 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.
+4. With `--map-existing`, maps archived project folder names onto existing target-root dirs by normalized name, e.g. `foldermd` -> `folder-md`.
+5. With `--existing-only`, skips archived projects that do not already have a mapped target dir. This prevents fresh-machine restores from creating stale duplicate folders.
+6. With `--skip-agent-auth`, restores only project `.env.local` files and leaves the new machine's active Claude/Codex/Cursor auth files untouched.
 
 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.
@@ -115,6 +122,8 @@ 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
+youmd env restore <vault> --root ~/Desktop/CODE_YOU --map-existing --existing-only --skip-agent-auth
+                                # safe fresh-machine restore into cloned project dirs
 ```
 
 The CLI wrapper delegates directly to these bash scripts via `spawnSync` with

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
 ```