create-egregore 0.17.3 → 0.18.0

package/bin/cli.js

@@ -1,24 +1,184 @@
 #!/usr/bin/env node
 
 /**
- * create-egregore — Set up Egregore in one command.
+ * create-egregore — set up Egregore for your team in one command.
+ *
+ *   - Installs an `egregore` PATH binary instead of a shell alias
+ *   - Auto-execs into the selected assistant (Claude Code or Codex) at the end
  *
  * Four modes:
- *   npx create-egregore --token st_xxxx   (from website — connected mode)
- *   npx create-egregore                    (interactive — API-based, existing)
- *   npx create-egregore --open            (local mode — founder, no API)
- *   npx create-egregore join <org>         (local mode — join existing)
+ *   npx -y create-egregore@latest --token st_xxxx    (from website)
+ *   npx -y create-egregore@latest                     (guided setup / launcher)
+ *   npx -y create-egregore@latest join <org>          (join existing)
  */
 
 const fs = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
+const { spawnSync } = require("node:child_process");
 const ui = require("../lib/ui");
 const { EgregoreAPI } = require("../lib/api");
-const { deviceFlow } = require("../lib/auth");
-const { install, ghApi } = require("../lib/setup");
+const {
+  canUseInteractiveBrowserFlow,
+  deviceFlow,
+  explainNoGhHeadless,
+  ghCliExists,
+  tryGhAuthOrLogin,
+} = require("../lib/auth");
+const {
+  hasCodexRuntimeSupport,
+  installCodexRuntime,
+  reportCodexRuntimeSummary,
+} = require("../lib/codex-runtime");
+const {
+  install,
+  ghApi,
+  registerInstance,
+  installLauncherBinary,
+  normalizeRuntime,
+} = require("../lib/setup");
 const { detectContext, isWritable, isSystemDir } = require("../lib/context");
 
 const API_URL = process.env.EGREGORE_API_URL || "https://egregore-production-55f2.up.railway.app";
+const INSTANCES_FILE = path.join(os.homedir(), ".egregore", "instances.json");
+
+function readLocalInstances() {
+  if (!fs.existsSync(INSTANCES_FILE)) return [];
+  try {
+    let data = JSON.parse(fs.readFileSync(INSTANCES_FILE, "utf-8"));
+    // Accept legacy/alt wrapped format: { instances: [...] }
+    if (data && !Array.isArray(data) && Array.isArray(data.instances)) {
+      data = data.instances;
+    }
+    if (!Array.isArray(data)) return [];
+    // Filter out invalid + dedup by resolved path. Some registries accumulated
+    // duplicate entries from old installers that didn't dedup on write.
+    const seen = new Set();
+    const result = [];
+    for (const entry of data) {
+      if (!entry || !entry.path || !fs.existsSync(entry.path)) continue;
+      const key = path.resolve(entry.path);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      result.push(entry);
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+// Detect whether `cwd` is itself an egregore install — even if cloned into a
+// dir with a non-canonical name (e.g. `curve-labs-core` instead of `egregore`).
+// Identified by structural artifacts (egregore.json + memory symlink), not by
+// directory name. Returns null when cwd is not an egregore.
+function detectCwdEgregore(cwd) {
+  const configPath = path.join(cwd, "egregore.json");
+  const memoryPath = path.join(cwd, "memory");
+  if (!fs.existsSync(configPath)) return null;
+  if (!fs.existsSync(memoryPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return {
+      path: cwd,
+      slug: config.slug || path.basename(cwd),
+      name: config.org_name || path.basename(cwd),
+      adopt: true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function binaryOnPath(bin) {
+  return spawnSync("which", [bin], { stdio: "pipe" }).status === 0;
+}
+
+function assistantLabel(runtime) {
+  return normalizeRuntime(runtime) === "codex" ? "Codex" : "Claude Code";
+}
+
+function upgradeCodexRuntimeForExisting(instances) {
+  for (const inst of instances) {
+    if (!inst || !inst.path || !fs.existsSync(inst.path)) continue;
+    try {
+      const summary = installCodexRuntime(inst.path);
+      const ready = hasCodexRuntimeSupport(inst.path);
+      reportCodexRuntimeSummary(summary, ui, {
+        label: `Codex runtime for ${inst.slug || inst.name || path.basename(inst.path)}`,
+        includeConflicts: !ready,
+      });
+    } catch (err) {
+      ui.warn(`Could not install Codex runtime for ${inst.path}: ${err.message}`);
+    }
+  }
+}
+
+async function chooseRuntime(args) {
+  if (args.runtime) {
+    try {
+      return normalizeRuntime(args.runtime);
+    } catch (err) {
+      ui.error(err.message);
+      process.exit(1);
+    }
+  }
+
+  if (!process.stdin.isTTY) return "claude-code";
+
+  const hasClaude = binaryOnPath("claude");
+  const hasCodex = binaryOnPath("codex");
+  const recommended = !hasClaude && hasCodex ? "codex" : "claude-code";
+  const choices = ["claude-code", "codex"]
+    .map((runtime) => {
+      const installed = runtime === "codex" ? hasCodex : hasClaude;
+      const label = assistantLabel(runtime);
+      const missingCopy = runtime === "codex"
+        ? "Install Codex later, then run egregore and choose Codex"
+        : "Install Claude Code later, then run egregore and choose Claude Code";
+      return {
+        label: `${label}${installed ? "" : " (not installed)"}${recommended === runtime ? " (recommended)" : ""}`,
+        description: installed
+          ? (runtime === "codex" ? "Installed · portable agent protocol" : "Installed · Claude Code integration")
+          : missingCopy,
+        runtime,
+        installed,
+      };
+    })
+    .sort((a, b) => Number(b.installed) - Number(a.installed));
+  const choice = await ui.choose("Which assistant do you want to use?", choices);
+  return choice.runtime;
+}
+
+async function upgradeLauncherFromExisting(instances) {
+  upgradeCodexRuntimeForExisting(instances);
+  const inst = instances.find((entry) => entry && entry.path && fs.existsSync(entry.path));
+  if (!inst) return null;
+  try {
+    return await installLauncherBinary(inst.path, ui);
+  } catch {
+    // Non-fatal: opening the launcher can still try PATH, and setup retries later.
+    return null;
+  }
+}
+
+function openLauncherBrowser(alias, runtimeOverride) {
+  const binary = (alias && alias.binaryPath) || "egregore";
+  const launcherArgs = [];
+  if (runtimeOverride) launcherArgs.push("--runtime", normalizeRuntime(runtimeOverride));
+  launcherArgs.push("browse");
+
+  const result = spawnSync(binary, launcherArgs, {
+    stdio: "inherit",
+    cwd: process.cwd(),
+    env: { ...process.env },
+  });
+  if (result.error) {
+    ui.warn(`Could not open the egregore launcher: ${result.error.message}`);
+    return false;
+  }
+  process.exit(result.signal ? 1 : (result.status ?? 0));
+}
 
 function parseArgs(argv) {
   const args = {};
@@ -32,8 +192,22 @@ function parseArgs(argv) {
       args.api = argv[++i];
     } else if (argv[i] === "--open") {
       args.open = true;
+    } else if (argv[i] === "--connected" || argv[i] === "--hosted") {
+      args.connected = true;
     } else if (argv[i] === "--force") {
       args.force = true;
+    } else if (argv[i] === "--no-autolaunch") {
+      args.noAutolaunch = true;
+    } else if (argv[i] === "--no-screens") {
+      args.noScreens = true;
+    } else if (argv[i] === "--codex") {
+      args.runtime = "codex";
+    } else if (argv[i] === "--claude" || argv[i] === "--claude-code") {
+      args.runtime = "claude-code";
+    } else if (argv[i] === "--runtime" && argv[i + 1]) {
+      args.runtime = argv[++i];
+    } else if (argv[i].startsWith("--runtime=")) {
+      args.runtime = argv[i].split("=")[1];
     } else if (argv[i] === "--help" || argv[i] === "-h") {
       args.help = true;
     } else if (!argv[i].startsWith("-")) {
@@ -61,24 +235,40 @@ async function maybeRedirect(force) {
   if (!ctx) return { targetDir: process.cwd(), prefilledRepo: null };
 
   const { repoName, parentDir, originOwner, originName } = ctx;
+  const cwdEgregore = detectCwdEgregore(ctx.toplevel);
+  const isInsideEgregore = !!cwdEgregore;
 
   // Non-TTY guard: we can't prompt. Fail loudly so CI/Docker/piped scripts
   // don't hang forever on readline.
   if (!process.stdin.isTTY) {
     console.log("");
-    ui.error(`Detected a git repo at ./${repoName} but stdin is not a TTY — cannot prompt.`);
-    ui.info("Re-run from outside the repo, or pass --force to install here anyway.");
+    if (isInsideEgregore) {
+      ui.error(`Detected an Egregore checkout at ./${repoName} but stdin is not a TTY — cannot prompt.`);
+      ui.info(`Re-run from ${parentDir}, or pass --force to install here anyway.`);
+    } else {
+      ui.error(`Detected a git repo at ./${repoName} but stdin is not a TTY — cannot prompt.`);
+      ui.info("Re-run from outside the repo, or pass --force to install here anyway.");
+    }
     process.exit(1);
   }
 
   const parentWritable = isWritable(parentDir);
   const parentIsSystem = isSystemDir(parentDir);
+  const fallbackDir = path.join(os.homedir(), "egregores");
+  const recommendedDir = parentWritable && !parentIsSystem ? parentDir : fallbackDir;
 
   console.log("");
-  ui.warn(`You're inside a git repo: ${ui.bold(`./${repoName}`)}`);
-  console.log("");
-  ui.info("Egregore lives as a sibling shell that manages your repos,");
-  ui.info("not inside them. Your repo stays where it is.");
+  if (isInsideEgregore) {
+    ui.warn(`You're inside an Egregore checkout: ${ui.bold(`./${repoName}`)}`);
+    console.log("");
+    ui.info("To set up another Egregore, put it next to this checkout.");
+    ui.info(`Recommended local path: ${ui.cyan(recommendedDir)}`);
+  } else {
+    ui.warn(`You're inside a git repo: ${ui.bold(`./${repoName}`)}`);
+    console.log("");
+    ui.info("Egregore lives as a sibling shell that manages your repos,");
+    ui.info("not inside them. Your repo stays where it is.");
+  }
 
   if (parentIsSystem) {
     console.log("");
@@ -86,8 +276,13 @@ async function maybeRedirect(force) {
   }
 
   const choices = [];
-  // Offer the parent redirect only if it's writable AND not a system dir.
-  if (parentWritable && !parentIsSystem) {
+  if (isInsideEgregore) {
+    choices.push({
+      label: "Use recommended local path",
+      description: recommendedDir,
+      action: "recommended",
+    });
+  } else if (parentWritable && !parentIsSystem) {
     choices.push({
       label: `Install in ${parentDir}`,
       description: `Set up alongside ${repoName} and add it to managed repos (Recommended)`,
@@ -95,8 +290,8 @@ async function maybeRedirect(force) {
     });
   }
   choices.push({
-    label: "Pick a different directory",
-    description: "Choose where to install Egregore",
+    label: "Choose another folder",
+    description: "Paste or type a local folder path",
     action: "pick",
   });
   choices.push({
@@ -113,7 +308,7 @@ async function maybeRedirect(force) {
     process.exit(0);
   }
 
-  let targetDir = parentDir;
+  let targetDir = choice.action === "recommended" ? recommendedDir : parentDir;
   if (choice.action === "pick") {
     const answer = await ui.prompt("Install directory (absolute path):");
     if (!answer) {
@@ -133,10 +328,19 @@ async function maybeRedirect(force) {
       process.exit(1);
     }
   }
+  if (choice.action === "recommended") {
+    try {
+      if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+      fs.accessSync(targetDir, fs.constants.W_OK);
+    } catch (err) {
+      ui.error(`Cannot write to ${targetDir}: ${err.message}`);
+      process.exit(1);
+    }
+  }
 
   return {
     targetDir,
-    prefilledRepo: {
+    prefilledRepo: isInsideEgregore ? null : {
       name: originName || repoName,
       owner: originOwner,
       localName: repoName,
@@ -147,21 +351,56 @@ async function maybeRedirect(force) {
 
 function showHelp() {
   ui.banner();
-  ui.info("Usage:");
-  ui.info("  npx create-egregore                          Interactive setup (API)");
-  ui.info("  npx create-egregore --open                  New project (local mode)");
-  ui.info("  npx create-egregore join <org>[/<repo>]       Join existing project");
-  ui.info("  npx create-egregore --token <setup-token>    Install from website");
+  ui.info("create-egregore — set up Egregore for your team in one command.");
   ui.info("");
-  ui.info("Options:");
-  ui.info("  --open            Local mode — no API server needed");
+  ui.info("Common:");
+  ui.info("  npx -y create-egregore@latest                          Create your Egregore (or open the launcher)");
+  ui.info("  npx -y create-egregore@latest join <org>[/<repo>]      Join existing project");
+  ui.info("  npx -y create-egregore@latest --token <setup-token>    Install from website");
+  ui.info("");
+  ui.info("Advanced options:");
+  ui.info("  --open            Local founder mode (now the default; flag kept for back-compat)");
+  ui.info("  --connected       Use the hosted egregore.xyz setup flow instead of local");
   ui.info("  --token <token>   Setup token from egregore.xyz");
-  ui.info("  --api <url>       API URL override");
+  ui.info("  --api <url>       Use connected API setup with this URL");
+  ui.info("  --codex           Prefer Codex for this local install");
+  ui.info("  --claude          Prefer Claude Code for this local install");
+  ui.info("  --runtime <name>  Assistant override: claude-code or codex");
   ui.info("  --force           Skip the in-repo detection check");
+  ui.info("  --no-autolaunch   Don't launch the assistant at the end (for CI)");
+  ui.info("  --no-screens      Skip the full-screen welcome/ready bookends");
   ui.info("  -h, --help        Show this help");
   ui.info("");
 }
 
+async function preflight() {
+  // Verify prerequisites before starting. Fast fail with specific fix hints
+  // beats discovering missing tools mid-install. Claude Code is checked
+  // separately at auto-exec time since users can install it after.
+  const { spawnSync } = require("node:child_process");
+  const checks = [
+    { bin: "git",    hint: "install Xcode command-line tools or https://git-scm.com" },
+    { bin: "jq",     hint: "brew install jq  (or https://stedolan.github.io/jq/)" },
+  ];
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  const missing = [];
+  if (nodeMajor < 18) {
+    missing.push({ bin: "node >=18", hint: `you're on Node ${process.versions.node}; upgrade at https://nodejs.org` });
+  }
+  for (const c of checks) {
+    const r = spawnSync("which", [c.bin], { stdio: "pipe" });
+    if (r.status !== 0) missing.push(c);
+  }
+  if (missing.length === 0) return;
+
+  ui.warn("missing prerequisites:");
+  for (const m of missing) {
+    ui.info(`  ${ui.red("✗")} ${ui.bold(m.bin)}  ${ui.dim("— " + m.hint)}`);
+  }
+  ui.info("");
+  process.exit(1);
+}
+
 async function main() {
   const args = parseArgs(process.argv);
 
@@ -169,10 +408,69 @@ async function main() {
     showHelp();
     process.exit(0);
   }
+  if (args.runtime) {
+    try {
+      args.runtime = normalizeRuntime(args.runtime);
+    } catch (err) {
+      ui.error(err.message);
+      process.exit(1);
+    }
+  }
 
-  ui.banner();
+  // Local-first product surface: if the user already has egregores installed
+  // and didn't pass an explicit mode flag, refresh the launcher and open the
+  // same TUI as bare `egregore`. With no installed instances, make bare
+  // `npx -y create-egregore@latest` enter the guided local founder setup (`--open`).
+  //
+  // We also surface the cwd as a launchable when it looks like an egregore
+  // install (egregore.json + memory symlink present) but isn't in the registry
+  // — common when the egregore was cloned into a non-canonical directory name
+  // and so its path was never recorded.
+  const noInstallFlags = !args.token && !args.open && !args.connected && !args.subcommand && !args.force && !args.api;
+  if (noInstallFlags && process.stdin.isTTY) {
+    const registered = readLocalInstances();
+    const cwdInstall = detectCwdEgregore(process.cwd());
+    const alreadyRegistered =
+      cwdInstall && registered.some((i) => path.resolve(i.path) === path.resolve(cwdInstall.path));
+    const instances =
+      cwdInstall && !alreadyRegistered ? [cwdInstall, ...registered] : registered;
+    if (instances.length > 0) {
+      if (cwdInstall && !alreadyRegistered) {
+        try {
+          registerInstance(cwdInstall.slug, cwdInstall.name, cwdInstall.path, args.runtime || "claude-code");
+        } catch {}
+      }
+      const alias = await upgradeLauncherFromExisting(instances);
+      if (openLauncherBrowser(alias, args.runtime)) return;
+      ui.warn("Falling back to guided local setup.");
+      args.open = true;
+    }
+    if (instances.length === 0) {
+      args.open = true;
+    }
+  }
+
+  // Bookend: full-screen welcome (alt-screen) or inline banner. Only one
+  // or the other — don't double up. `--no-screens` and non-TTY fall back
+  // to the inline banner.
+  const useScreens = !args.noScreens && ui.canShowScreens();
+  if (useScreens) {
+    const mode = args.subcommand === "join" ? "join"
+      : args.token ? "token"
+      : args.open ? "founder"
+      : "founder";
+    await ui.welcomeScreen({ mode });
+  } else {
+    ui.banner();
+  }
+
+  await preflight();
 
   const ctx = await maybeRedirect(args.force);
+  // Thread install options through ctx so downstream flows can use them.
+  ctx.noAutolaunch = !!args.noAutolaunch;
+  ctx.noScreens = !useScreens;
+  ctx.runtime = await chooseRuntime(args);
 
   if (args.token) {
     // ===== Connected mode: token provided =====
@@ -181,19 +479,20 @@ async function main() {
   } else if (args.subcommand === "join") {
     // ===== Local mode: join existing =====
     if (!args.joinOrg) {
-      ui.error("Usage: npx create-egregore join <github-org>");
+      ui.error("Usage: npx -y create-egregore@latest join <github-org>");
       process.exit(1);
     }
     const { localJoinFlow } = require("../lib/local");
     await localJoinFlow(args.joinOrg, ui, ctx);
-  } else if (args.open) {
-    // ===== Local mode: founder (explicit opt-in) =====
-    const { localFounderFlow } = require("../lib/local");
-    await localFounderFlow(ui, ctx);
-  } else {
-    // ===== Interactive API flow (default — existing behavior) =====
+  } else if (args.connected) {
+    // ===== Connected/hosted interactive flow (explicit opt-in) =====
     const api = new EgregoreAPI(args.api || API_URL);
     await interactiveFlow(api, ctx);
+  } else {
+    // ===== Local founder is the DEFAULT — bare `npx create-egregore` and
+    //       --open both land here. Hosted is opt-in via --connected/--token.
+    const { localFounderFlow } = require("../lib/local");
+    await localFounderFlow(ui, ctx);
   }
 }
 
@@ -209,19 +508,34 @@ async function tokenFlow(api, token, ctx) {
     ui.info("");
     ui.info("The token may have expired or already been used.");
     ui.info("Visit egregore.xyz to get a new one, or run without --token:");
-    ui.info("  npx create-egregore");
+    ui.info("  npx -y create-egregore@latest");
     process.exit(1);
   }
 
-  // Joiner tokens don't include a github_token — run device flow to get one
+  // Joiner tokens don't include a github_token — try gh CLI first. If gh is
+  // installed but logged out, run gh auth login instead of device flow.
   if (!data.github_token || data.needs_cli_auth) {
-    ui.info("\nSign in with GitHub to complete setup.\n");
-    try {
-      data.github_token = await deviceFlow(ui);
-      ui.success("Authenticated with GitHub");
-    } catch (err) {
-      ui.error(`GitHub auth failed: ${err.message}`);
+    const ghAuth = tryGhAuthOrLogin(ui, data.needs_cli_auth ? { mode: "join" } : {});
+    if (ghAuth) {
+      ui.success(`Using your ${ui.bold("gh")} CLI auth${ghAuth.user ? ` (${ghAuth.user})` : ""}`);
+      data.github_token = ghAuth.token;
+    } else if (ghCliExists()) {
+      ui.error("GitHub CLI auth did not complete.");
+      ui.info(`Run ${ui.bold("gh auth login")} and then re-run this command.`);
       process.exit(1);
+    } else {
+      if (!canUseInteractiveBrowserFlow()) {
+        explainNoGhHeadless(ui);
+        process.exit(1);
+      }
+      ui.info("\nSign in to your GitHub to complete setup.\n");
+      try {
+        data.github_token = await deviceFlow(ui, data.needs_cli_auth ? { mode: "join" } : {});
+        ui.success("Authenticated with GitHub");
+      } catch (err) {
+        ui.error(`GitHub auth failed: ${err.message}`);
+        process.exit(1);
+      }
     }
   }
 
@@ -236,7 +550,13 @@ async function tokenFlow(api, token, ctx) {
     }
   }
   try {
-    await install(data, ui, ctx.targetDir, { skipRepos });
+    await install(data, ui, ctx.targetDir, {
+      skipRepos,
+      noAutolaunch: ctx.noAutolaunch,
+      noScreens: ctx.noScreens,
+      flowVariant: ctx.flowVariant,
+      runtime: ctx.runtime,
+    });
     if (ctx.prefilledRepo && skipRepos.size === 0) {
       console.log("");
       ui.info(`Tip: add your current repo to managed_repos with:`);
@@ -249,15 +569,30 @@ async function tokenFlow(api, token, ctx) {
 }
 
 async function interactiveFlow(api, ctx) {
-  // 1. GitHub auth
-  ui.info("Let's set up Egregore. First, sign in with GitHub.\n");
+  // 1. GitHub auth — gh CLI if available, else device flow.
   let githubToken;
-  try {
-    githubToken = await deviceFlow(ui);
-    ui.success("Authenticated with GitHub");
-  } catch (err) {
-    ui.error(`GitHub auth failed: ${err.message}`);
+  const ghAuth = tryGhAuthOrLogin(ui);
+  if (ghAuth) {
+    ui.success(`Using your ${ui.bold("gh")} CLI auth${ghAuth.user ? ` (${ghAuth.user})` : ""}`);
+    githubToken = ghAuth.token;
+  } else if (ghCliExists()) {
+    ui.error("GitHub CLI auth did not complete.");
+    ui.info(`Run ${ui.bold("gh auth login")} and then re-run this command.`);
     process.exit(1);
+  } else {
+    if (!canUseInteractiveBrowserFlow()) {
+      explainNoGhHeadless(ui);
+      process.exit(1);
+    }
+    ui.info("Let's set up Egregore in your own account. First, sign in to your GitHub.\n");
+    try {
+      // Connected mode enumerates orgs server-side, so it needs read:org here.
+      githubToken = await deviceFlow(ui, { scope: "repo read:org" });
+      ui.success("Authenticated with GitHub");
+    } catch (err) {
+      ui.error(`GitHub auth failed: ${err.message}`);
+      process.exit(1);
+    }
   }
 
   // 2. Detect orgs
@@ -280,9 +615,13 @@ async function interactiveFlow(api, ctx) {
   for (const org of orgsData.orgs) {
     if (org.has_egregore) {
       for (const inst of org.instances || []) {
+        const desc =
+          inst.org_name && inst.org_name !== inst.repo_name
+            ? `Join existing · ${inst.org_name}`
+            : "Join existing";
         choices.push({
-          label: `${org.name || org.login} — ${inst.org_name || inst.repo_name}`,
-          description: "Join existing",
+          label: `${org.name || org.login} — ${inst.repo_name}`,
+          description: desc,
           action: "join",
           login: org.login,
           repo_name: inst.repo_name,
@@ -312,9 +651,13 @@ async function interactiveFlow(api, ctx) {
   // Personal account — show join for each existing instance + setup for new
   if (orgsData.personal.has_egregore) {
     for (const inst of orgsData.personal.instances || []) {
+      const desc =
+        inst.org_name && inst.org_name !== inst.repo_name
+          ? `Join existing · ${inst.org_name}`
+          : "Join existing";
       choices.push({
-        label: `${orgsData.user.login} (personal) — ${inst.org_name || inst.repo_name}`,
-        description: "Join existing",
+        label: `${orgsData.user.login} (personal) — ${inst.repo_name}`,
+        description: desc,
         action: "join",
         login: orgsData.user.login,
         repo_name: inst.repo_name,
@@ -394,32 +737,68 @@ async function setupFlow(api, githubToken, choice, ctx) {
     selectedRepos.unshift(autoAdopt);
   }
 
-  // Offer to create a new project repo
+  // Offer to create a new project repo. Pre-validate against the predicted
+  // egregore + memory repo names so the user can't accidentally create
+  // (or worse, "add an existing" via 422-fallback) a repo that collides
+  // with their Egregore instance.
+  const slugifyRepo = (s) => s.trim().toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  const predictedEgregoreRepo = instanceName
+    ? `egregore-${slugifyRepo(instanceName)}`
+    : "egregore";
+  const predictedMemoryRepo = instanceName
+    ? `${slugifyRepo(instanceName)}-memory`
+    : `${slugifyRepo(choice.login)}-memory`;
+
   console.log("");
-  const newRepoName = await ui.prompt("Create a new project repo? Enter name (or press Enter to skip):");
-  if (newRepoName) {
-    const repoSlug = newRepoName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-    if (repoSlug) {
-      const s2 = ui.spinner(`Creating ${repoSlug}...`);
-      try {
-        const apiPath = choice.is_personal ? "/user/repos" : `/orgs/${choice.login}/repos`;
-        const { status } = await ghApi("POST", apiPath, githubToken, {
-          name: repoSlug,
-          private: true,
-          auto_init: true,
-        });
-        if (status === 201 || status === 200) {
-          selectedRepos.push(repoSlug);
-          s2.stop(`Created ${repoSlug}`);
-        } else if (status === 422) {
-          selectedRepos.push(repoSlug);
-          s2.stop(`${repoSlug} already exists — added to managed repos`);
-        } else {
-          s2.fail(`Could not create ${repoSlug}`);
-        }
-      } catch (err) {
-        s2.fail(`Could not create ${repoSlug}: ${err.message}`);
+  let projectRepoSlug = null;
+  while (true) {
+    const newRepoName = await ui.prompt("Create a new project repo? Enter name (or press Enter to skip):");
+    if (!newRepoName) break;
+    const repoSlug = slugifyRepo(newRepoName);
+    if (!repoSlug) {
+      ui.warn("That doesn't produce a valid repo name. Try letters, numbers, and dashes.");
+      continue;
+    }
+    if (repoSlug === predictedEgregoreRepo) {
+      ui.warn(`"${repoSlug}" collides with your Egregore repo. Pick a different name.`);
+      ui.info(`  ${ui.dim("suggestion:")} ${ui.cyan(`${repoSlug}-app`)}`);
+      continue;
+    }
+    if (repoSlug === predictedMemoryRepo) {
+      ui.warn(`"${repoSlug}" collides with your memory repo. Pick a different name.`);
+      continue;
+    }
+    projectRepoSlug = repoSlug;
+    break;
+  }
+  if (projectRepoSlug) {
+    const s2 = ui.spinner(`Creating ${projectRepoSlug}...`);
+    try {
+      const apiPath = choice.is_personal ? "/user/repos" : `/orgs/${choice.login}/repos`;
+      const { status } = await ghApi("POST", apiPath, githubToken, {
+        name: projectRepoSlug,
+        private: true,
+        auto_init: true,
+      });
+      if (status === 201 || status === 200) {
+        selectedRepos.push(projectRepoSlug);
+        s2.stop(`Created ${projectRepoSlug}`);
+      } else if (status === 422) {
+        // Repo already exists. We pre-validated against egregore + memory
+        // names, so this is a NEW conflict (some other repo of the user's
+        // already has this name). Surface and add as managed — same UX as
+        // before but with the accidental-collision-on-egregore-name path
+        // already filtered out.
+        selectedRepos.push(projectRepoSlug);
+        s2.stop(`${projectRepoSlug} already exists — added to managed repos`);
+      } else {
+        s2.fail(`Could not create ${projectRepoSlug}`);
       }
+    } catch (err) {
+      s2.fail(`Could not create ${projectRepoSlug}: ${err.message}`);
     }
   }
 
@@ -446,7 +825,13 @@ async function setupFlow(api, githubToken, choice, ctx) {
     // Claim the token immediately
     const data = await api.claimToken(result.setup_token);
     const skipRepos = autoAdopt ? new Set([autoAdopt]) : new Set();
-    await install(data, ui, ctx.targetDir, { skipRepos });
+    await install(data, ui, ctx.targetDir, {
+      skipRepos,
+      noAutolaunch: ctx.noAutolaunch,
+      noScreens: ctx.noScreens,
+      flowVariant: ctx.flowVariant,
+      runtime: ctx.runtime,
+    });
 
     if (result.telegram_invite_link) {
       console.log("");
@@ -477,7 +862,13 @@ async function joinFlow(api, githubToken, choice, ctx) {
         if (n && n === ctx.prefilledRepo.name) skipRepos.add(n);
       }
     }
-    await install(data, ui, ctx.targetDir, { skipRepos });
+    await install(data, ui, ctx.targetDir, {
+      skipRepos,
+      noAutolaunch: ctx.noAutolaunch,
+      noScreens: ctx.noScreens,
+      flowVariant: ctx.flowVariant,
+      runtime: ctx.runtime,
+    });
   } catch (err) {
     s.fail("Join failed");
     ui.error(err.message);