create-egregore 0.17.3 → 0.18.0

package/lib/setup.js

@@ -3,10 +3,15 @@
  * Zero dependencies — uses node:child_process, node:fs, node:path, node:os.
  */
 
-const { execSync, execFileSync } = require("node:child_process");
+const { execSync, execFileSync, spawnSync, spawn } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 const os = require("node:os");
+const {
+  hasCodexRuntimeSupport,
+  installCodexRuntime,
+  reportCodexRuntimeSummary,
+} = require("./codex-runtime");
 
 const https = require("node:https");
 
@@ -57,7 +62,9 @@ function ghApi(method, apiPath, token, body) {
 function initMemoryDirs(memoryDir) {
   const dirs = [
     "people",
+    "invites",
     "handoffs",
+    "knowledge/questions",
     "knowledge/decisions",
     "knowledge/patterns",
     "knowledge/findings",
@@ -96,6 +103,202 @@ async function acceptPendingInvitations(githubToken, githubOrg, ui) {
   }
 }
 
+// Normalize a git URL for equality comparison: strip protocol, .git suffix,
+// SSH-vs-HTTPS distinction. github.com:org/repo / https://github.com/org/repo
+// / git@github.com:org/repo all reduce to the same canonical form.
+function normalizeGitUrl(url) {
+  if (!url) return "";
+  let u = url.trim().replace(/\.git$/i, "");
+  u = u.replace(/^git@([^:]+):/, "$1/");
+  u = u.replace(/^https?:\/\//i, "");
+  return u.toLowerCase();
+}
+
+function gitRemoteMatches(repoDir, expectedUrl) {
+  try {
+    const url = execFileSync("git", ["-C", repoDir, "remote", "get-url", "origin"], {
+      stdio: "pipe", encoding: "utf-8", timeout: 5000,
+    }).trim();
+    return normalizeGitUrl(url) === normalizeGitUrl(expectedUrl);
+  } catch {
+    return false;
+  }
+}
+
+// True only when every artifact the installer would produce is already in
+// place AND pointing at the right remotes. Used to short-circuit a re-run
+// of the clone/symlink steps when the user is just rejoining what they
+// already have on disk.
+function isFullySetUp(egregoreDir, memoryDir, forkUrl, memoryUrl) {
+  if (!fs.existsSync(path.join(egregoreDir, ".git"))) return false;
+  if (!gitRemoteMatches(egregoreDir, forkUrl)) return false;
+  if (!fs.existsSync(path.join(memoryDir, ".git"))) return false;
+  if (!gitRemoteMatches(memoryDir, memoryUrl)) return false;
+  if (!fs.existsSync(path.join(egregoreDir, "memory"))) return false;
+  if (!fs.existsSync(path.join(egregoreDir, ".env"))) return false;
+  if (!fs.existsSync(path.join(egregoreDir, "egregore.json"))) return false;
+  return true;
+}
+
+function slugifyName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function normalizeUsageType(data = {}) {
+  if (data.usage_type === "founder_group" || data.usage_type === "joiner_group") {
+    return data.usage_type;
+  }
+  if (data.onboarding_role === "founder" || data.role === "founder") return "founder_group";
+  return "joiner_group";
+}
+
+function mergeProfileFields(existing, additions = []) {
+  const fields = Array.isArray(existing) ? existing.filter(Boolean) : [];
+  if (!fields.includes("name")) fields.push("name");
+  for (const field of additions) {
+    if (field && !fields.includes(field)) fields.push(field);
+  }
+  return fields;
+}
+
+function personProfileContent(state = {}, opts = {}) {
+  const now = opts.onboardedAt || new Date().toISOString();
+  const username = state.github_username || opts.githubUsername || "unknown";
+  const displayName = state.display_name || state.github_name || username;
+  const role = state.member_role || state.onboarding?.member_role || opts.memberRole || "Member";
+  return [
+    `# ${displayName}`,
+    "",
+    `GitHub: ${username}`,
+    `Role: ${role}`,
+    `Joined: ${now.split("T")[0]}`,
+    `Onboarded: ${now}`,
+    "",
+  ].join("\n");
+}
+
+function ensurePersonOnboardingWitness(memoryDir, state = {}, opts = {}) {
+  const username = state.github_username || opts.githubUsername;
+  if (!memoryDir || !username) return null;
+  const peopleDir = path.join(memoryDir, "people");
+  fs.mkdirSync(peopleDir, { recursive: true });
+  const personFile = path.join(peopleDir, `${username}.md`);
+  const witness = personProfileContent(state, opts);
+  let next = witness;
+
+  if (fs.existsSync(personFile)) {
+    const current = fs.readFileSync(personFile, "utf-8");
+    if (/^Onboarded:/m.test(current)) return personFile;
+    if (/^---\s*$/m.test(current) && current.trimStart().startsWith("---")) {
+      const body = current.match(/^---[\s\S]*?---\s*\n([\s\S]*)$/m)?.[1]?.trim();
+      next = body ? `${witness}\n${body}\n` : witness;
+    } else if (current.trimStart().startsWith("# ")) {
+      next = `${current.replace(/\s*$/, "")}\nOnboarded: ${opts.onboardedAt || new Date().toISOString()}\n`;
+    } else if (current.trim()) {
+      next = `${witness}\n${current.trim()}\n`;
+    }
+  }
+
+  fs.writeFileSync(personFile, next);
+  try {
+    const rel = path.relative(memoryDir, personFile);
+    run(`git add ${JSON.stringify(rel)}`, { cwd: memoryDir });
+    run(`git commit -m ${JSON.stringify(`Onboard ${username}`)}`, { cwd: memoryDir });
+    run("git push", { cwd: memoryDir });
+  } catch {}
+  return personFile;
+}
+
+async function ensureInstallerMemberRole(data = {}, existingState = {}, ui) {
+  const existing = data.member_role || existingState.member_role || existingState.onboarding?.member_role;
+  if (existing) return existing;
+  const usageType = normalizeUsageType(data);
+  const fallback = usageType === "founder_group" ? "Founder" : "Member";
+  if (!process.stdin.isTTY) return fallback;
+  console.log("");
+  const answer = await ui.prompt("What's your role here?", { default: fallback });
+  return answer || fallback;
+}
+
+function buildOnboardingState(existing = {}, data = {}, opts = {}) {
+  const state = { ...existing };
+  const preferredRuntime = normalizeRuntime(opts.runtime);
+  const githubUsername = data.github_username || state.github_username || "";
+  const githubName = data.github_name || state.github_name || githubUsername;
+  const displayName = data.display_name || state.display_name || githubName || githubUsername;
+  const usageType = normalizeUsageType(data);
+  const memberRole = data.member_role || state.member_role || state.onboarding?.member_role || "";
+  const requestedComplete =
+    opts.onboardingComplete === true ||
+    data.onboarding_complete === true ||
+    data.onboarding_complete === "true";
+  const alreadyComplete =
+    state.onboarding_complete === true ||
+    state.onboarding_complete === "true";
+  const shouldComplete = alreadyComplete || (requestedComplete && !!memberRole);
+
+  if (githubUsername) state.github_username = githubUsername;
+  if (githubName) state.github_name = githubName;
+  if (displayName) {
+    state.display_name = displayName;
+    state.name = state.name || slugifyName(displayName) || githubUsername;
+  }
+  if (memberRole) state.member_role = memberRole;
+  if (data.github_email || data.email) state.email = data.github_email || data.email;
+
+  state.onboarding_complete = shouldComplete;
+  state.usage_type = usageType;
+  state.org_setup = true;
+  state.github_configured = true;
+  state.workspace_ready = true;
+  if (data.transcript_sharing !== undefined) {
+    state.transcript_sharing = data.transcript_sharing;
+  }
+  if (opts.flowVariant) {
+    state.flow_variant = opts.flowVariant;
+  } else if (data.flow_variant) {
+    state.flow_variant = data.flow_variant;
+  }
+  state.preferred_runtime = preferredRuntime;
+  state.profile_fields_collected = mergeProfileFields(state.profile_fields_collected, memberRole ? ["role"] : []);
+  state.onboarding = state.onboarding || {};
+  if (memberRole) state.onboarding.member_role = memberRole;
+  if (state.onboarding_complete) {
+    state.onboarding.phase = "complete";
+    state.onboarding.completed_at = state.onboarding.completed_at || new Date().toISOString();
+  } else {
+    state.onboarding.phase = state.onboarding.phase || "orient";
+    state.onboarding.started_at = state.onboarding.started_at || new Date().toISOString();
+  }
+  state.onboarding.installer_captured = true;
+  state.onboarding.invite_handled_by =
+    data.invite_handled_by || state.onboarding.invite_handled_by || "installer";
+  if (data.invite_skipped !== undefined) {
+    state.onboarding.invite_skipped = !!data.invite_skipped;
+  } else if (usageType === "founder_group" && state.onboarding.invite_skipped === undefined) {
+    state.onboarding.invite_skipped = true;
+  }
+  if (data.onboarding_role || data.role) {
+    state.onboarding.role = data.onboarding_role || data.role;
+  }
+  return state;
+}
+
+async function ensureInstallerDisplayName(data, existingState, ui) {
+  if (data.display_name || existingState.display_name) return data.display_name || existingState.display_name;
+  const fallback = data.github_name || data.github_username;
+  if (!fallback) return "";
+  if (!process.stdin.isTTY) return fallback;
+  console.log("");
+  const answer = await ui.prompt(`What should we call you? [${fallback}]:`);
+  return answer || fallback;
+}
+
 /**
  * Full local setup from claimed token data.
  *
@@ -108,11 +311,12 @@ async function acceptPendingInvitations(githubToken, githubOrg, ui) {
  *   avoid clobbering uncommitted work or pushing branches to their origin.
  */
 async function install(data, ui, targetDir, opts = {}) {
-  const { fork_url, memory_url, github_token, org_name, github_org, slug, api_key, repos = [], telegram_group_link, github_username, github_name, transcript_sharing } = data;
+  const { fork_url, memory_url, github_token, org_name, github_org, slug, api_key, repos = [], telegram_group_link, github_username, github_name } = data;
   const base = targetDir || process.cwd();
   const skipRepos = opts.skipRepos instanceof Set ? opts.skipRepos : new Set();
+  const preferredRuntime = normalizeRuntime(opts.runtime);
 
-  // Directory name from fork URL (what git clone would use), e.g. "egregore-core"
+  // Directory name from fork URL (what git clone would use), e.g. "egregore"
   const forkDirName = fork_url.split("/").pop().replace(/\.git$/, "");
   const egregoreDir = path.join(base, forkDirName);
   const memoryDirName = memory_url
@@ -123,67 +327,80 @@ async function install(data, ui, targetDir, opts = {}) {
 
   const totalSteps = 5 + repos.length;
 
+  // Detect a complete prior install at this target so "Join existing" doesn't
+  // re-walk the 7-step setup for a user who already has everything wired up.
+  // We still rewrite credentials / state / register (steps 4–5) so tokens
+  // refresh and the registry entry is current — only the noisy clone+symlink
+  // steps are skipped. Falls through to the normal flow if anything is off.
+  const alreadyInstalled = isFullySetUp(egregoreDir, memoryDir, fork_url, memory_url);
+
   // Accept pending repo collaboration invitations (joiners get invited as collaborators)
+  if (github_token) configureGitCredentials(github_token);
   await acceptPendingInvitations(github_token, github_org, ui);
 
-  // 1. Clone fork (SSH first, HTTPS fallback — no token embedding)
-  ui.step(1, totalSteps, "Cloning egregore...");
-  if (fs.existsSync(egregoreDir)) {
-    ui.warn("egregore/ already exists — pulling latest");
-    run("git pull", { cwd: egregoreDir });
+  if (alreadyInstalled) {
+    ui.success(`Already installed at ${ui.bold(egregoreDir)} — refreshing setup`);
+    console.log("");
   } else {
-    if (!cloneRepo(fork_url, egregoreDir)) {
-      throw new Error(`Command failed: git clone ${fork_url} ${egregoreDir}\nCloning into '${egregoreDir}'...\nMake sure you have SSH keys set up or run 'gh auth login' first.`);
+    // 1. Clone fork (SSH first, HTTPS fallback — no token embedding)
+    ui.step(1, totalSteps, "Cloning egregore...");
+    if (fs.existsSync(egregoreDir)) {
+      ui.warn("egregore/ already exists — pulling latest");
+      run("git pull", { cwd: egregoreDir });
+    } else {
+      if (!cloneRepo(fork_url, egregoreDir)) {
+        throw new Error(`Command failed: git clone ${fork_url} ${egregoreDir}\nCloning into '${egregoreDir}'...\nMake sure you have SSH keys set up or run 'gh auth login' first.`);
+      }
     }
-  }
-  try { run("git config credential.helper store", { cwd: egregoreDir }); } catch {}
-  ensureDevelop(egregoreDir);
-  ui.success("Cloned egregore");
+    try { run("git config credential.helper store", { cwd: egregoreDir }); } catch {}
+    ensureDevelop(egregoreDir);
+    ui.success("Cloned egregore");
 
-  // Set repo-local git identity from GitHub user (not machine-global config)
-  if (github_username) {
-    try {
-      run(`git config user.name "${github_name || github_username}"`, { cwd: egregoreDir });
-      run(`git config user.email "${github_username}@users.noreply.github.com"`, { cwd: egregoreDir });
-    } catch {
-      // Non-fatal
+    // Set repo-local git identity from GitHub user (not machine-global config)
+    if (github_username) {
+      try {
+        run(`git config user.name "${github_name || github_username}"`, { cwd: egregoreDir });
+        run(`git config user.email "${github_username}@users.noreply.github.com"`, { cwd: egregoreDir });
+      } catch {
+        // Non-fatal
+      }
     }
-  }
 
-  // 2. Clone memory
-  ui.step(2, totalSteps, "Cloning shared memory...");
-  if (fs.existsSync(memoryDir)) {
-    ui.warn(`${memoryDirName}/ already exists — pulling latest`);
-    run("git pull", { cwd: memoryDir });
-  } else {
-    if (!cloneRepo(memory_url, memoryDir)) {
-      ui.warn(`Could not clone memory repo — you may need SSH keys or 'gh auth login'`);
+    // 2. Clone memory
+    ui.step(2, totalSteps, "Cloning shared memory...");
+    if (fs.existsSync(memoryDir)) {
+      ui.warn(`${memoryDirName}/ already exists — pulling latest`);
+      run("git pull", { cwd: memoryDir });
+    } else {
+      if (!cloneRepo(memory_url, memoryDir)) {
+        ui.warn(`Could not clone memory repo — you may need SSH keys or 'gh auth login'`);
+      }
     }
-  }
-  try { run("git config credential.helper store", { cwd: memoryDir }); } catch {}
-  if (github_username) {
-    try {
-      run(`git config user.name "${github_name || github_username}"`, { cwd: memoryDir });
-      run(`git config user.email "${github_username}@users.noreply.github.com"`, { cwd: memoryDir });
-    } catch {}
-  }
-  ui.success("Cloned memory");
+    try { run("git config credential.helper store", { cwd: memoryDir }); } catch {}
+    if (github_username) {
+      try {
+        run(`git config user.name "${github_name || github_username}"`, { cwd: memoryDir });
+        run(`git config user.email "${github_username}@users.noreply.github.com"`, { cwd: memoryDir });
+      } catch {}
+    }
+    ui.success("Cloned memory");
 
-  // 3. Symlink (use junction on Windows — no admin required)
-  ui.step(3, totalSteps, "Linking memory...");
-  const symlinkTarget = path.join(egregoreDir, "memory");
-  if (fs.existsSync(symlinkTarget)) {
-    ui.warn("memory/ symlink already exists");
-  } else {
-    if (process.platform === "win32") {
-      // Junctions require absolute paths on Windows
-      fs.symlinkSync(path.resolve(memoryDir), symlinkTarget, "junction");
+    // 3. Symlink (use junction on Windows — no admin required)
+    ui.step(3, totalSteps, "Linking memory...");
+    const symlinkTarget = path.join(egregoreDir, "memory");
+    if (fs.existsSync(symlinkTarget)) {
+      ui.warn("memory/ symlink already exists");
     } else {
-      const relPath = path.relative(egregoreDir, memoryDir);
-      fs.symlinkSync(relPath, symlinkTarget);
+      if (process.platform === "win32") {
+        // Junctions require absolute paths on Windows
+        fs.symlinkSync(path.resolve(memoryDir), symlinkTarget, "junction");
+      } else {
+        const relPath = path.relative(egregoreDir, memoryDir);
+        fs.symlinkSync(relPath, symlinkTarget);
+      }
     }
+    ui.success("Linked");
   }
-  ui.success("Linked");
 
   // 4. Write .env (secrets only — never committed to git)
   ui.step(4, totalSteps, "Writing credentials...");
@@ -199,19 +416,15 @@ async function install(data, ui, targetDir, opts = {}) {
   if (fs.existsSync(statePath)) {
     try { state = JSON.parse(fs.readFileSync(statePath, "utf-8")); } catch {}
   }
-  if (github_username) {
-    state.github_username = github_username;
-    state.github_name = github_name || github_username;
-  }
-  state.onboarding_complete = false;
-  state.usage_type = "joiner_group";
-  state.org_setup = true;
-  state.github_configured = true;
-  state.workspace_ready = true;
-  if (transcript_sharing !== undefined) {
-    state.transcript_sharing = transcript_sharing;
-  }
+  const displayName = await ensureInstallerDisplayName(data, state, ui);
+  const memberRole = await ensureInstallerMemberRole(data, state, ui);
+  state = buildOnboardingState(state, { ...data, display_name: displayName, member_role: memberRole }, {
+    runtime: preferredRuntime,
+    flowVariant: opts.flowVariant,
+    onboardingComplete: opts.onboardingComplete !== false,
+  });
   fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+  try { ensurePersonOnboardingWitness(memoryDir, state); } catch {}
 
   // 4c. Ensure mode is set in egregore.json (connected mode for API-based setup)
   const configPath = path.join(egregoreDir, "egregore.json");
@@ -225,10 +438,15 @@ async function install(data, ui, targetDir, opts = {}) {
     } catch {}
   }
 
-  // 5. Register instance + shell alias
+  // 4d. Overlay packaged Codex support before registering or launching. This
+  // makes cloned public templates usable even before the public repo syncs.
+  const codexRuntime = installCodexRuntime(egregoreDir);
+  reportCodexRuntimeSummary(codexRuntime, ui);
+
+  // 5. Register instance + install launcher binary
   ui.step(5, totalSteps, "Registering instance...");
-  registerInstance(forkDirName, org_name, egregoreDir);
-  const alias = await installShellAlias(egregoreDir, ui);
+  registerInstance(forkDirName, org_name, egregoreDir, preferredRuntime);
+  const alias = await installLauncherBinary(egregoreDir, ui);
 
   // 6+. Clone managed repos (if any)
   const clonedRepos = [];
@@ -264,24 +482,59 @@ async function install(data, ui, targetDir, opts = {}) {
     }
   }
 
-  // Done
-  console.log("");
-  ui.success(`Egregore is ready for ${ui.bold(org_name)}`);
-  console.log("");
-  ui.info(`Your workspace:`);
-  ui.info(`  ${ui.cyan(`./${forkDirName}/`)}  — Your Egregore instance`);
-  ui.info(`  ${ui.cyan(`./${memoryDirName}/`)}     — Shared knowledge`);
-  for (const repoName of clonedRepos) {
-    ui.info(`  ${ui.cyan(`./${repoName}/`)}        — Managed repo`);
-  }
+  // Warm the npx cache for egregore-artifacts so the first /view or
+  // publish-artifact call doesn't pay a cold npm download (~5-10s).
+  // Background + detached — we don't care about completion, and any
+  // failure is silent. The first real use benefits if this finishes in
+  // time, otherwise it costs nothing.
+  try {
+    const { spawn } = require("child_process");
+    const warm = spawn("npx", ["-y", "egregore-artifacts@latest", "--help"], {
+      detached: true,
+      stdio: "ignore",
+    });
+    warm.unref();
+  } catch { /* ignore — cosmetic warmup */ }
+
+  // Done — full-screen summary bookend if we can; inline workspace list
+  // otherwise. Same contract as localFounderFlow.
+  const workspaces = [
+    { label: `./${forkDirName}/`, description: "your Egregore instance" },
+    { label: `./${memoryDirName}/`, description: "shared knowledge" },
+    ...clonedRepos.map((rn) => ({ label: `./${rn}/`, description: "managed repo" })),
+  ];
   if (telegram_group_link) {
+    workspaces.push({ label: telegram_group_link, description: "telegram group" });
+  }
+  const usageType = normalizeUsageType(data);
+  const setupSummary = {
+    workspace: "created",
+    invite: usageType === "joiner_group" ? "accepted" : (data.invite_skipped ? "skipped" : "handled"),
+    telegram: telegram_group_link ? "connected" : "skipped",
+    assistant: runtimeDisplay(preferredRuntime),
+    command: "run egregore anytime",
+  };
+
+  const ui_ = require("./ui");
+  if (!opts.noScreens && ui_.canShowScreens()) {
+    const result = await ui_.summaryScreen({ orgName: org_name, workspaces, setup: setupSummary });
+    if (result === "escape") opts.noAutolaunch = true;
+  } else {
+    ui.section("You're done", `Egregore is ready for ${ui.bold(org_name)}`);
+    ui.info(`${ui.green("●")} workspace   ${setupSummary.workspace}`);
+    ui.info(`${ui.green("●")} invite      ${setupSummary.invite}`);
+    ui.info(`${ui.green("●")} Telegram    ${setupSummary.telegram}`);
+    ui.info(`${ui.green("●")} assistant   ${setupSummary.assistant}`);
+    ui.info(`${ui.green("●")} next        ${setupSummary.command}`);
+    console.log("");
+    ui.info(`Your workspace:`);
+    for (const ws of workspaces) {
+      ui.info(`  ${ui.cyan(ws.label)}   ${ui.dim(ws.description || "")}`);
+    }
     console.log("");
-    ui.info(`Join the Telegram group for notifications:`);
-    ui.info(`  ${ui.cyan(telegram_group_link)}`);
   }
-  console.log("");
-  ui.info(`Next: open a ${ui.bold("new terminal")} and type ${ui.bold(alias.aliasName)} to start.`);
-  console.log("");
+
+  await launchOrInstruct(path.join(base, forkDirName), alias, ui, opts);
 }
 
 /**
@@ -342,13 +595,28 @@ function toSSH(url) {
   return m ? `git@github.com:${m[1]}.git` : null;
 }
 
+/**
+ * Environment for git clone/fetch during install. GIT_TERMINAL_PROMPT=0
+ * stops the hanging username/password prompt; BatchMode makes the SSH-first
+ * attempt fail fast on machines without keys instead of blocking the install
+ * on an interactive "Are you sure you want to continue connecting?" host-key
+ * prompt mid-spinner (fresh machines have no github.com in known_hosts).
+ */
+function gitCloneEnv(base = process.env) {
+  return {
+    ...base,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_SSH_COMMAND: base.GIT_SSH_COMMAND || "ssh -oBatchMode=yes",
+  };
+}
+
 /**
  * Clone a repo, trying SSH first then HTTPS (no token embedded).
  * The repo:invite-scoped OAuth token can't clone — we rely on the
  * user's own git credentials (SSH keys / gh CLI / credential helper).
  */
 function cloneRepo(httpsUrl, dir, timeout = 60000) {
-  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+  const env = gitCloneEnv();
   const sshUrl = toSSH(httpsUrl);
 
   if (sshUrl) {
@@ -383,7 +651,145 @@ function configureGitCredentials(token) {
   }
 }
 
-function registerInstance(slug, name, egregoreDir) {
+function normalizeRuntime(runtime) {
+  const raw = String(runtime || "claude-code").trim().toLowerCase();
+  if (raw === "claude" || raw === "claude-code" || raw === "claude_code") return "claude-code";
+  if (raw === "codex" || raw === "openai-codex" || raw === "openai_codex") return "codex";
+  throw new Error(`Unsupported Egregore runtime: ${runtime}`);
+}
+
+function runtimeDisplay(runtime) {
+  return normalizeRuntime(runtime) === "codex" ? "Codex" : "Claude Code";
+}
+
+function runtimeBinary(runtime) {
+  return normalizeRuntime(runtime) === "codex" ? "codex" : "claude";
+}
+
+// One-line install command for the chosen assistant — shown when the
+// install finishes on a machine that doesn't have the assistant yet.
+function assistantInstallCommand(runtime) {
+  return normalizeRuntime(runtime) === "codex"
+    ? "npm install -g @openai/codex"
+    : "npm install -g @anthropic-ai/claude-code";
+}
+
+function runtimeLaunchArgs(runtime, egregoreDir) {
+  if (normalizeRuntime(runtime) === "codex") {
+    return [
+      "--enable", "hooks",
+      "--sandbox", "danger-full-access",
+      "--ask-for-approval", "never",
+      "--cd", egregoreDir,
+    ];
+  }
+  return ["start"];
+}
+
+function startSpinner(label) {
+  if (!process.stdout.isTTY) {
+    console.log(`  ${label}...`);
+    return () => {};
+  }
+  const frames = ["|", "/", "-", "\\"];
+  let i = 0;
+  process.stdout.write(`  ${frames[i]} ${label}`);
+  const timer = setInterval(() => {
+    i = (i + 1) % frames.length;
+    process.stdout.write(`\r  ${frames[i]} ${label}\x1b[K`);
+  }, 90);
+  return () => {
+    clearInterval(timer);
+    process.stdout.write("\r\x1b[K");
+  };
+}
+
+function runCapturedWithSpinner(cmd, args, options, label) {
+  return new Promise((resolve) => {
+    const stop = startSpinner(label);
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = spawn(cmd, args, {
+      cwd: options.cwd,
+      env: options.env || process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      stop();
+      resolve({ status: 1, stdout, stderr: stderr || String(err) });
+    });
+    child.on("close", (status) => {
+      if (settled) return;
+      settled = true;
+      stop();
+      resolve({ status, stdout, stderr });
+    });
+  });
+}
+
+async function renderCodexStartupCard(egregoreDir) {
+  const script = path.join(egregoreDir, "bin", "codex-session-start.sh");
+  if (fs.existsSync(script)) {
+    try {
+      const result = await runCapturedWithSpinner("bash", [script], {
+        cwd: egregoreDir,
+      }, "Preparing Codex startup");
+      if (result.stdout) process.stdout.write(result.stdout);
+      if (result.status !== 0 && result.stderr) process.stderr.write(result.stderr);
+      if (result.status === 0) return true;
+    } catch {}
+  }
+  return false;
+}
+
+function codexSupportMessage(egregoreDir) {
+  return [
+    "Codex assistant support is missing from this Egregore checkout.",
+    `  path: ${egregoreDir}`,
+    "",
+    "This checkout needs a newer Egregore core with:",
+    "  bin/codex-session-start.sh",
+    "  bin/codex-install-skills.sh",
+    "  .codex/config.toml",
+    "  .codex/skills/",
+    "  .codex/hooks.json",
+    "  .codex/hooks/",
+    "",
+    "Run npx -y create-egregore@latest to install the packaged Codex runtime, then rerun egregore.",
+    "Egregore workflows appear as slash commands. In Codex, invoke them with the matching $skill token or ask in natural language.",
+  ].join("\n");
+}
+
+function hasCodexCoreSupport(egregoreDir) {
+  return hasCodexRuntimeSupport(egregoreDir);
+}
+
+function installCodexSkills(egregoreDir) {
+  const script = path.join(egregoreDir, "bin", "codex-install-skills.sh");
+  if (!fs.existsSync(script)) return false;
+  try {
+    const result = spawnSync("bash", [script], {
+      cwd: egregoreDir,
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "pipe"],
+      maxBuffer: 1024 * 1024,
+    });
+    return result.status === 0;
+  } catch {}
+  return false;
+}
+
+function commandExists(bin) {
+  return spawnSync("which", [bin], { stdio: "pipe" }).status === 0;
+}
+
+function registerInstance(slug, name, egregoreDir, runtime) {
   const registryDir = path.join(os.homedir(), ".egregore");
   const registryFile = path.join(registryDir, "instances.json");
 
@@ -394,15 +800,28 @@ function registerInstance(slug, name, egregoreDir) {
   let instances = [];
   if (fs.existsSync(registryFile)) {
     try {
-      instances = JSON.parse(fs.readFileSync(registryFile, "utf-8"));
+      const parsed = JSON.parse(fs.readFileSync(registryFile, "utf-8"));
+      // Accept either the canonical [..] or the legacy/alt {instances: [..]}
+      // shape. Subsequent writes normalize back to a plain array.
+      if (Array.isArray(parsed)) {
+        instances = parsed;
+      } else if (parsed && Array.isArray(parsed.instances)) {
+        instances = parsed.instances;
+      }
     } catch {
       instances = [];
     }
   }
 
-  const entry = { slug, name, path: egregoreDir };
   // Dedup by path (not slug) so multiple instances from the same org can coexist
   const idx = instances.findIndex((i) => i.path === egregoreDir);
+  const previous = idx >= 0 ? instances[idx] : {};
+  const entry = { ...previous, slug, name, path: egregoreDir };
+  if (runtime) {
+    entry.runtime = normalizeRuntime(runtime);
+  } else if (!entry.runtime && entry.preferred_runtime) {
+    entry.runtime = normalizeRuntime(entry.preferred_runtime);
+  }
   if (idx >= 0) {
     instances[idx] = entry;
   } else {
@@ -412,6 +831,331 @@ function registerInstance(slug, name, egregoreDir) {
   fs.writeFileSync(registryFile, JSON.stringify(instances, null, 2) + "\n");
 }
 
+// ── Auto-launch helper ─────────────────────────────────────────────
+//
+// Replaces the legacy "open a new terminal and type <alias>" closing with an
+// actual agent-runtime invocation in the egregore directory. The installer
+// process waits for the runtime to exit, then propagates the exit code.
+//
+// ctx.noAutolaunch=true disables this (for CI / scripted installs) and falls
+// back to printing the command the user should type.
+// A child process can't change the parent shell's PATH, so right after install
+// the launcher works in any NEW shell but not the current one (its rc hasn't
+// re-loaded). Detect that and give the exact fix — avoids a confusing
+// "egregore: command not found" when the user types it again in this shell.
+function launcherNextStep(ui, aliasName) {
+  const binDir = path.join(os.homedir(), ".local", "bin");
+  const onPath = (process.env.PATH || "").split(path.delimiter).some((p) => {
+    try { return p && path.resolve(p) === binDir; } catch { return false; }
+  });
+  if (onPath) return `type ${ui.bold(aliasName)} in any terminal.`;
+  const shell = (process.env.SHELL || "").split("/").pop();
+  const rc = shell === "zsh" ? "~/.zshrc" : "~/.bashrc";
+  return `type ${ui.bold(aliasName)} in a new terminal — or run ${ui.bold("source " + rc)} in this one.`;
+}
+
+async function launchOrInstruct(egregoreDir, alias, ui, ctx = {}) {
+  const aliasName = (alias && alias.aliasName) || "egregore";
+  const runtime = normalizeRuntime(ctx.runtime);
+  const display = runtimeDisplay(runtime);
+  const binary = runtimeBinary(runtime);
+
+  if (ctx.noAutolaunch) {
+    ui.info(`Next: ${launcherNextStep(ui, aliasName)}`);
+    console.log("");
+    return;
+  }
+
+  if (!commandExists(binary)) {
+    const hasClaude = commandExists("claude");
+    const hasCodex = commandExists("codex");
+    // The user already chose `runtime` at the picker — lead with installing
+    // THAT one ("install Codex first"), then offer the other as an alternative.
+    const other = runtime === "codex" ? "claude-code" : "codex";
+    if (!hasClaude && !hasCodex) {
+      ui.warn(`Almost there — install ${display} to start sessions.`);
+      ui.info(`  Install ${display} first:`);
+      ui.info(`    ${ui.bold(assistantInstallCommand(runtime))}`);
+      ui.info(`  ${ui.dim(`(or use ${runtimeDisplay(other)}: ${assistantInstallCommand(other)})`)}`);
+      ui.info(`  Then ${launcherNextStep(ui, aliasName)}`);
+      console.log("");
+      return;
+    }
+    ui.warn(`Almost there — Egregore needs ${display} to run your sessions.`);
+    ui.info(`  Install ${display} first:`);
+    ui.info(`    ${ui.bold(assistantInstallCommand(runtime))}`);
+    ui.info(`  Then ${launcherNextStep(ui, aliasName)}`);
+    if (runtime === "codex") ui.info("  Choose Codex when prompted.");
+    console.log("");
+    return;
+  }
+
+  ui.info(`Starting Egregore in ${ui.bold(display)} now — press ${ui.bold("Ctrl+D")} (or /exit) to return to your shell.`);
+  ui.info(`Next time, ${launcherNextStep(ui, aliasName)}`);
+  console.log("");
+
+  if (runtime === "codex") {
+    const codexRuntime = installCodexRuntime(egregoreDir);
+    reportCodexRuntimeSummary(codexRuntime, ui);
+    if (!hasCodexCoreSupport(egregoreDir)) {
+      ui.warn(codexSupportMessage(egregoreDir));
+      ui.info(`Run ${ui.bold(aliasName)} after updating the checkout.`);
+      console.log("");
+      return;
+    }
+    const skillsInstalled = installCodexSkills(egregoreDir);
+    const cardRendered = await renderCodexStartupCard(egregoreDir);
+    if (!skillsInstalled || !cardRendered) {
+      ui.warn(codexSupportMessage(egregoreDir));
+      ui.info(`Run ${ui.bold(aliasName)} after updating the checkout.`);
+      console.log("");
+      return;
+    }
+  }
+
+  const result = spawnSync(binary, runtimeLaunchArgs(runtime, egregoreDir), {
+    cwd: egregoreDir,
+    stdio: "inherit",
+    env: { ...process.env, EGREGORE_RUNTIME: runtime },
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+// Launcher binary template path. We ship a Node-based TUI launcher as the
+// primary; the shell script remains in the repo for back-compat but the
+// installer prefers the .js variant because it provides the full-screen
+// browser, better rendering, and richer keybinds.
+const LAUNCHER_TEMPLATE_JS = path.join(__dirname, "..", "assets", "egregore-launcher.js");
+const LAUNCHER_TEMPLATE_SH = path.join(__dirname, "..", "assets", "egregore-launcher.sh");
+
+function readLauncherTemplate() {
+  // Prefer the Node launcher; fall back to bash only if the .js is missing.
+  if (fs.existsSync(LAUNCHER_TEMPLATE_JS)) return fs.readFileSync(LAUNCHER_TEMPLATE_JS, "utf-8");
+  return fs.readFileSync(LAUNCHER_TEMPLATE_SH, "utf-8");
+}
+
+function currentTemplatePath() {
+  return fs.existsSync(LAUNCHER_TEMPLATE_JS) ? LAUNCHER_TEMPLATE_JS : LAUNCHER_TEMPLATE_SH;
+}
+
+// Parse a semver from a version-stamp comment. Accepts both styles so we can
+// upgrade a bash launcher to the Node launcher across a major line:
+//   # egregore-launcher-version: X.Y.Z   (bash)
+//   // egregore-launcher-version: X.Y.Z  (node)
+function launcherVersion(contents) {
+  const m = contents.match(/egregore-launcher-version:\s*(\d+\.\d+\.\d+)/);
+  return m ? m[1] : null;
+}
+
+// Return 1 if a > b, -1 if a < b, 0 if equal. Both are semver strings "x.y.z".
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+function isDirWritable(dir) {
+  try {
+    if (!fs.existsSync(dir)) return false;
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function dirOnPath(dir) {
+  const pathEntries = (process.env.PATH || "").split(path.delimiter);
+  return pathEntries.some((p) => {
+    try {
+      return p && fs.existsSync(p) && fs.realpathSync(p) === fs.realpathSync(dir);
+    } catch {
+      return p === dir;
+    }
+  });
+}
+
+function appendLocalBinToRc(ui) {
+  // Ensure ~/.local/bin is on PATH for future shells by appending to rc files.
+  // Idempotent — only appends if the export line isn't already present.
+  const rcFiles = [".zshrc", ".bashrc", ".bash_profile"].map((f) => path.join(os.homedir(), f));
+  const exportLine = `export PATH="$HOME/.local/bin:$PATH"`;
+  let touched = [];
+  for (const rc of rcFiles) {
+    if (!fs.existsSync(rc)) continue;
+    try {
+      const content = fs.readFileSync(rc, "utf-8");
+      if (content.includes(`$HOME/.local/bin`) || content.includes(`${os.homedir()}/.local/bin`)) continue;
+      fs.appendFileSync(rc, `\n# Added by create-egregore\n${exportLine}\n`);
+      touched.push(path.basename(rc));
+    } catch {}
+  }
+  if (touched.length > 0) {
+    ui.info(`Added ~/.local/bin to PATH in: ${touched.join(", ")} (takes effect in new shells).`);
+  }
+}
+
+/**
+ * Install the `egregore` PATH binary. Writes a launcher script that reads
+ * ~/.egregore/instances.json and launches the chosen instance.
+ *
+ * Placement preference:
+ *   1. /usr/local/bin/egregore (writable without sudo)
+ *   2. /opt/homebrew/bin/egregore (Apple Silicon Homebrew, writable without sudo)
+ *   3. ~/.local/bin/egregore + PATH append (no sudo; works in new shells)
+ *
+ * If an `egregore` binary already exists at the chosen path:
+ *   - Same content (by byte match) → no-op (silent)
+ *   - Different content → keep existing, warn (don't clobber user customizations)
+ *
+ * Returns { aliasName: "egregore", binaryPath, location, replaced }
+ */
+async function installLauncherBinary(egregoreDir, ui) {
+  const template = readLauncherTemplate();
+  const candidates = [
+    { dir: "/usr/local/bin", location: "system" },
+    { dir: "/opt/homebrew/bin", location: "system" },
+    { dir: path.join(os.homedir(), ".local", "bin"), location: "user" },
+  ];
+
+  let chosen = null;
+  for (const c of candidates) {
+    if (c.location === "user" && !fs.existsSync(c.dir)) {
+      try {
+        fs.mkdirSync(c.dir, { recursive: true });
+      } catch {
+        continue;
+      }
+    }
+    if (isDirWritable(c.dir)) {
+      chosen = c;
+      break;
+    }
+  }
+
+  if (!chosen) {
+    ui.warn("Could not find a writable bin directory. Install the launcher manually:");
+    ui.info(`  cp ${currentTemplatePath()} ~/.local/bin/egregore && chmod +x ~/.local/bin/egregore`);
+    return { aliasName: "egregore", binaryPath: null, location: null, replaced: false };
+  }
+
+  const binaryPath = path.join(chosen.dir, "egregore");
+  let replaced = false;
+
+  if (fs.existsSync(binaryPath)) {
+    try {
+      const existing = fs.readFileSync(binaryPath, "utf-8");
+      if (existing === template) {
+        // Same content — silent no-op, still chmod for safety
+        try { fs.chmodSync(binaryPath, 0o755); } catch {}
+        if (chosen.location === "user" && !dirOnPath(chosen.dir)) appendLocalBinToRc(ui);
+        removeShadowingEgregoreAliases(ui);
+        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+      }
+
+      // Different content — decide upgrade vs preserve via version stamps.
+      const existingVer = launcherVersion(existing);
+      const templateVer = launcherVersion(template);
+
+      if (existingVer && templateVer) {
+        if (compareVersions(templateVer, existingVer) > 0) {
+          // Template is newer — safe upgrade.
+          fs.writeFileSync(binaryPath, template, { mode: 0o755 });
+          ui.success(`Upgraded ${ui.dim("egregore")} at ${binaryPath} ${ui.dim(`(${existingVer} → ${templateVer})`)}`);
+          if (chosen.location === "user" && !dirOnPath(chosen.dir)) appendLocalBinToRc(ui);
+          removeShadowingEgregoreAliases(ui);
+          return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: true };
+        }
+        if (compareVersions(templateVer, existingVer) < 0) {
+          // Template is older — don't downgrade. Warn lightly.
+          ui.warn(`Existing ${binaryPath} (v${existingVer}) is newer than this installer's template (v${templateVer}) — leaving it alone.`);
+          removeShadowingEgregoreAliases(ui);
+          return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+        }
+        // Equal stamps but different content → user edited the file. Don't clobber.
+        ui.warn(`Existing ${binaryPath} has been edited locally — not overwriting.`);
+        ui.info(`  To reset: cp ${currentTemplatePath()} ${binaryPath}`);
+        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+      }
+
+      // No version stamp on existing. If it looks like one of OUR old
+      // launchers (pre-0.4.1, before stamps existed), upgrade it. Otherwise
+      // assume the user customized it and preserve.
+      // Match both the bash (REGISTRY=…) and Node (path.join(os.homedir()…))
+      // forms, plus a generic substring that's stable across versions.
+      const looksLikeOurs =
+        existing.includes(`.egregore/instances.json`) ||
+        existing.includes(`egregore-launcher-version`);
+      if (looksLikeOurs) {
+        fs.writeFileSync(binaryPath, template, { mode: 0o755 });
+        ui.success(`Upgraded ${ui.dim("egregore")} at ${binaryPath} ${ui.dim(`(pre-0.4.1 → ${templateVer})`)}`);
+        if (chosen.location === "user" && !dirOnPath(chosen.dir)) appendLocalBinToRc(ui);
+        removeShadowingEgregoreAliases(ui);
+        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: true };
+      }
+      ui.warn(`Existing ${binaryPath} doesn't look like an egregore launcher — not overwriting.`);
+      ui.info(`  If you meant to install: rm ${binaryPath} and re-run create-egregore.`);
+      return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+    } catch {
+      // Fall through to write
+    }
+  }
+
+  try {
+    fs.writeFileSync(binaryPath, template, { mode: 0o755 });
+    replaced = false;
+  } catch (err) {
+    ui.warn(`Could not write launcher to ${binaryPath}: ${err.message}`);
+    return { aliasName: "egregore", binaryPath: null, location: null, replaced: false };
+  }
+
+  if (chosen.location === "user" && !dirOnPath(chosen.dir)) {
+    appendLocalBinToRc(ui);
+  }
+
+  removeShadowingEgregoreAliases(ui);
+  ui.success(`Installed ${ui.dim("egregore")} at ${binaryPath}`);
+  return { aliasName: "egregore", binaryPath, location: chosen.location, replaced };
+}
+
+// Strip legacy `alias egregore=...` lines from common shell rc files. These
+// come from older `create-egregore` installs that shipped a shell alias
+// instead of a PATH binary. In zsh, aliases beat PATH lookups, so the alias
+// shadows the new launcher and `egregore` keeps running the alias's
+// `cd <dir> && claude start` even after the launcher is installed.
+// Idempotent: if no alias exists, nothing happens. Non-fatal on errors.
+function removeShadowingEgregoreAliases(ui) {
+  const home = os.homedir();
+  const targets = [
+    { rcPath: path.join(home, ".zshrc"), prefix: "alias egregore=" },
+    { rcPath: path.join(home, ".bashrc"), prefix: "alias egregore=" },
+    { rcPath: path.join(home, ".bash_profile"), prefix: "alias egregore=" },
+    { rcPath: path.join(home, ".profile"), prefix: "alias egregore=" },
+    { rcPath: path.join(home, ".config", "fish", "config.fish"), prefix: "alias egregore " },
+  ];
+  const touched = [];
+  for (const { rcPath, prefix } of targets) {
+    if (!fs.existsSync(rcPath)) continue;
+    try {
+      const content = fs.readFileSync(rcPath, "utf-8");
+      const lines = content.split("\n");
+      const kept = lines.filter((l) => !l.startsWith(prefix));
+      if (kept.length === lines.length) continue;
+      fs.writeFileSync(rcPath, kept.join("\n"));
+      touched.push(path.basename(rcPath));
+    } catch {
+      // Non-fatal — best effort. Worst case: the alias stays and the user
+      // can remove it by hand.
+    }
+  }
+  if (touched.length > 0 && ui) {
+    ui.info(`Removed legacy ${ui.bold("egregore")} alias from ${touched.join(", ")} — start a new shell to use the launcher.`);
+  }
+}
+
 async function installShellAlias(egregoreDir, ui) {
   try {
     // Detect shell profile
@@ -497,9 +1241,17 @@ module.exports = {
   ghApi,
   acceptPendingInvitations,
   registerInstance,
+  normalizeRuntime,
   installShellAlias,
+  installLauncherBinary,
+  launchOrInstruct,
+  buildOnboardingState,
+  ensurePersonOnboardingWitness,
+  ensureInstallerMemberRole,
   embedToken,
   configureGitCredentials,
+  gitCloneEnv,
+  assistantInstallCommand,
   initMemoryDirs,
   ensureDevelop,
   run,