create-egregore 0.17.4 → 0.18.1

package/lib/local.js

@@ -6,19 +6,35 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { execFileSync } = require("node:child_process");
-const { deviceFlow, openBrowser } = require("./auth");
 const {
+  GH_INSTALL_URL,
+  ghCliExists,
+  ghInstallCommand,
+  ghInstallShellCommand,
+  openBrowser,
+  runGhInstallAndLogin,
+  tryGhAuthOrLogin,
+} = require("./auth");
+const { installCodexRuntime, reportCodexRuntimeSummary } = require("./codex-runtime");
+const {
+  install,
   ghApi,
   acceptPendingInvitations,
   registerInstance,
-  installShellAlias,
+  normalizeRuntime,
+  installLauncherBinary,
+  launchOrInstruct,
   embedToken,
   configureGitCredentials,
+  gitCloneEnv,
   initMemoryDirs,
   ensureDevelop,
+  ensurePersonOnboardingWitness,
+  ensureInstallerMemberRole,
   run,
 } = require("./setup");
 const { EgregoreAPI } = require("./api");
+const { joinCommand } = require("./commands");
 
 // Template repo for new egregore instances (OSS)
 const TEMPLATE_OWNER = "egregore-labs";
@@ -38,6 +54,18 @@ async function listOrgs(token) {
   return data.map((o) => ({ login: o.login }));
 }
 
+async function listOrgMembers(token, org) {
+  // Returns [{login}]. Only visible members (public or visible to the token).
+  // Non-fatal on error — caller falls back to a text prompt.
+  try {
+    const { status, data } = await ghApi("GET", `/orgs/${org}/members?per_page=100`, token);
+    if (status !== 200 || !Array.isArray(data)) return [];
+    return data.map((m) => ({ login: m.login }));
+  } catch {
+    return [];
+  }
+}
+
 async function repoExists(token, owner, repo) {
   const { status } = await ghApi("GET", `/repos/${owner}/${repo}`, token);
   return status === 200;
@@ -116,9 +144,19 @@ async function putFileContent(token, owner, repo, filePath, content, message) {
 
 async function listOrgRepos(token, owner, isOrg) {
   // Fetch all repos (public + private). Paginate to get beyond the first 100.
+  //
+  // For ORGS: /orgs/{owner}/repos?type=all returns everything the token can
+  // see in that org (public + private + member-of) given `repo` scope.
+  //
+  // For PERSONAL: /users/{owner}/repos returns ONLY public repos — the
+  // endpoint doesn't honor the token's `repo` scope for private listings.
+  // The right endpoint for "this authenticated user's own repos" is
+  // /user/repos, which returns public + private + collaborator with `repo`
+  // scope. We filter affiliation=owner so we don't surface random collab
+  // repos in the founder's picker.
   const baseUrl = isOrg
     ? `/orgs/${owner}/repos?per_page=100&sort=updated&type=all`
-    : `/users/${owner}/repos?per_page=100&sort=updated&type=owner`;
+    : `/user/repos?per_page=100&sort=updated&affiliation=owner`;
 
   let allRepos = [];
   let page = 1;
@@ -131,6 +169,14 @@ async function listOrgRepos(token, owner, isOrg) {
     page++;
   }
 
+  // Personal /user/repos returns repos across all of the user's accounts
+  // (their personal namespace + any orgs they're a member of). When the
+  // caller asked for the personal scope, narrow to repos owned by `owner`
+  // so org repos don't pollute the personal picker.
+  if (!isOrg) {
+    allRepos = allRepos.filter((r) => r.owner && r.owner.login === owner);
+  }
+
   return allRepos
     .filter((r) => !r.archived && r.name !== "egregore" && !r.name.endsWith("-memory"))
     .map((r) => ({ name: r.name, language: r.language || "", description: r.description || "" }));
@@ -176,6 +222,7 @@ function cloneRepo(url, dir, token, ui, label) {
       stdio: "pipe",
       encoding: "utf-8",
       timeout: 60000,
+      env: gitCloneEnv(),
     });
     try {
       run(`git remote set-url origin ${url}`, { cwd: dir });
@@ -201,7 +248,7 @@ function toSSH(url) {
  * GIT_TERMINAL_PROMPT=0 prevents the hanging username/password prompt.
  */
 function cloneWithFallback(httpsUrl, dir, timeout = 60000) {
-  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+  const env = gitCloneEnv();
   const sshUrl = toSSH(httpsUrl);
 
   // Try SSH first (most devs have SSH keys; GitHub no longer supports HTTPS password auth)
@@ -243,52 +290,263 @@ function createSymlink(egregoreDir, memoryDir, ui) {
   ui.success("Linked");
 }
 
-// GitHub App installation URL — grants Egregore access to repos the user selects
-const APP_INSTALL_URL = "https://github.com/apps/egregore-labs/installations/new";
+// Retry an async fn until it returns truthy, up to `attempts` tries with a
+// fixed delay between them. Returns the last result (truthy on success).
+async function retryAsync(fn, attempts = 2, delayMs = 1500) {
+  let result;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      result = await fn();
+    } catch {
+      result = false;
+    }
+    if (result) return result;
+    if (i < attempts - 1) await new Promise((r) => setTimeout(r, delayMs));
+  }
+  return result;
+}
+
+// Shown when gh isn't installed. gh is GitHub's own CLI — it signs the user in
+// locally so the installer can work with THEIR repos. No Egregore OAuth app, no
+// third-party "requesting access" screen. Language stays ownership-first: this
+// is their machine and their repos; Egregore isn't managing or holding anything.
+function ghFallbackNote(ui) {
+  const lines = [
+    `Egregore sets up in your own GitHub, on your own machine — you own all of it.`,
+    `It signs in with GitHub CLI (${ui.cyan("gh")}), GitHub's own tool, so setup can see`,
+    `your repos and create your Egregore. No third-party access screen, nothing hosted by us.`,
+    ``,
+    `Install gh, sign in, then re-run — that's the whole setup:`,
+    `  1. ${ui.bold(ghInstallCommand())}`,
+    `  2. ${ui.bold("gh auth login")}`,
+    `  3. ${ui.bold("npx -y create-egregore@latest")}`,
+    ``,
+    `${ui.dim("Install for any OS: " + GH_INSTALL_URL)}`,
+  ];
+  return lines;
+}
+
+function repoEntryName(entry) {
+  return typeof entry === "string" ? entry : entry && entry.name;
+}
+
+function yamlList(values) {
+  const clean = values.filter(Boolean);
+  if (clean.length === 0) return " []";
+  return clean.map((v) => `\n  - ${String(v).replace(/\n/g, " ")}`).join("");
+}
+
+function inviteFilename(username) {
+  const safe = String(username || "invitee")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-|-$/g, "") || "invitee";
+  return `${new Date().toISOString().slice(0, 10)}-${safe}.md`;
+}
+
+function writeInviteArtifact(memoryDir, invite) {
+  const invitesDir = path.join(memoryDir, "invites");
+  fs.mkdirSync(invitesDir, { recursive: true });
+  const file = path.join(invitesDir, inviteFilename(invite.invitee));
+  const managedRepos = (invite.managedRepos || []).map(repoEntryName).filter(Boolean);
+  const lines = [
+    "---",
+    "type: egregore_invite",
+    `created_at: ${new Date().toISOString()}`,
+    `inviter: ${invite.inviter}`,
+    `invitee_github: ${invite.invitee}`,
+    `org: ${invite.githubOrg}`,
+    `repo: ${invite.githubOrg}/${invite.repoName}`,
+    `memory_repo: ${invite.memoryRepo}`,
+    `managed_repos:${yamlList(managedRepos)}`,
+    `invite_url: ${invite.inviteUrl || ""}`,
+    `fallback_command: ${invite.fallbackCommand}`,
+    `telegram_group_link: ${invite.telegramGroupLink || ""}`,
+    `delivery: ${invite.delivery || "copyable_share_block"}`,
+    "---",
+    "",
+    `# Invite: ${invite.invitee}`,
+    "",
+    `Fallback command: \`${invite.fallbackCommand}\``,
+    "",
+  ];
+  if (invite.inviteUrl) lines.push(`Invite URL: ${invite.inviteUrl}`, "");
+  if (invite.telegramGroupLink) lines.push(`Telegram: ${invite.telegramGroupLink}`, "");
+  fs.writeFileSync(file, lines.join("\n"));
+  return file;
+}
+
+function commitMemoryInvite(memoryDir, paths, username) {
+  if (!fs.existsSync(path.join(memoryDir, ".git"))) {
+    return { committed: false, pushed: false };
+  }
+  try {
+    for (const p of paths.filter(Boolean)) {
+      run(`git add ${JSON.stringify(path.relative(memoryDir, p))}`, { cwd: memoryDir });
+    }
+    run(`git commit -m "Invite ${username}"`, { cwd: memoryDir });
+    try {
+      run("git push", { cwd: memoryDir });
+      return { committed: true, pushed: true };
+    } catch {
+      return { committed: true, pushed: false };
+    }
+  } catch {
+    return { committed: false, pushed: false };
+  }
+}
+
+function telegramBotInviteLink(slug) {
+  return `https://t.me/Egregore_clbot?startgroup=org_${encodeURIComponent(slug || "egregore")}`;
+}
+
+function looksLikeUrl(value) {
+  return /^https?:\/\//i.test(String(value || "").trim());
+}
+
+async function maybeSetupTelegramGroup(ui, {
+  egregoreDir,
+  githubToken,
+  githubOrg,
+  repoName,
+  egreConfig,
+  statePath,
+}) {
+  ui.section("Telegram group", "optional shared notifications before you invite teammates");
+  const shouldSetup = await ui.confirm("Set up a Telegram group now?", false);
+  const botLink = telegramBotInviteLink(egreConfig.slug);
+
+  let state = {};
+  try { state = JSON.parse(fs.readFileSync(statePath, "utf-8")); } catch {}
+  state.telegram_setup = state.telegram_setup || {};
+  state.telegram_setup.handled_by = "installer";
+  state.telegram_setup.bot_invite_link = botLink;
+  state.telegram_setup.skipped = !shouldSetup;
+
+  if (!shouldSetup) {
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+    ui.info(`You can run ${ui.bold("/telegram-connect")} later. Invites will include the CLI join command only.`);
+    return { setup: false, groupLink: "" };
+  }
+
+  ui.note([
+    "Step 1: In Telegram, create a new group or open an existing team group.",
+    "Step 2: Add the Egregore bot to that group.",
+    "Step 3: Come back here and press Enter.",
+  ]);
+  ui.info(`Bot add link: ${ui.cyan(botLink)}`);
+  openBrowser(botLink);
+
+  await ui.prompt("Press Enter here after the bot is in the group");
+  ui.note([
+    "Step 4: In Telegram, copy a group invite link.",
+    "Paste it below so teammate invites include the Telegram group too.",
+    "If you skip this, Egregore will still work, but invites will not include Telegram.",
+  ]);
+
+  const groupLink = await ui.prompt("Telegram group join link (paste here, or Enter to skip)");
+  const cleaned = groupLink.trim();
+  let storedGroupLink = "";
+  if (cleaned && !looksLikeUrl(cleaned)) {
+    ui.warn("That does not look like a URL, so I will not store it.");
+  } else if (cleaned) {
+    storedGroupLink = cleaned;
+    egreConfig.telegram_group_link = cleaned;
+    state.telegram_group_link = cleaned;
+    state.telegram_setup.group_link = cleaned;
+
+    const configPath = path.join(egregoreDir, "egregore.json");
+    fs.writeFileSync(configPath, JSON.stringify(egreConfig, null, 2) + "\n");
+    try {
+      await putFileContent(
+        githubToken,
+        githubOrg,
+        repoName,
+        "egregore.json",
+        JSON.stringify(egreConfig, null, 2) + "\n",
+        "Configure Telegram group",
+      );
+    } catch {}
+    try {
+      run("git add egregore.json", { cwd: egregoreDir });
+      run('git commit -m "Configure Telegram group"', { cwd: egregoreDir });
+      run("git push", { cwd: egregoreDir });
+    } catch {}
+  }
+
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+  ui.success(storedGroupLink ? "Telegram group recorded" : "Telegram bot added; no group link saved");
+  return { setup: true, groupLink: storedGroupLink };
+}
 
 // ── Flow 1: Founder (local mode) ───────────────────────────────────
 
 async function localFounderFlow(ui, ctx = {}) {
+  const preferredRuntime = normalizeRuntime(ctx.runtime);
   // Names of repos already on disk as the user's own workdir — skip clone/pull.
   const skipRepos = ctx.skipRepos instanceof Set ? new Set(ctx.skipRepos) : new Set();
-  // 1. Install GitHub App — user picks which repos/accounts to grant access to
-  ui.info("Let's set up Egregore.\n");
-  ui.info("First, install the Egregore app on your GitHub account.");
-  ui.info("You'll choose exactly which repos to share.\n");
-  openBrowser(APP_INSTALL_URL);
-  await ui.prompt("Press Enter when done...");
-
-  // 2. GitHub auth (auto-approved after App install)
-  ui.info("");
+
+  // 1. GitHub auth — prefer the gh CLI. If gh is installed but logged out,
+  //    run gh auth login instead of opening the Egregore App page. The App
+  //    fallback is only for machines without gh.
+  ui.section("Connect your GitHub", "sign in to your own account — everything created is yours");
+  ui.note([
+    "Egregore builds in your GitHub and on your machine — you own all of it.",
+    "This CLI just helps you set it up. Nothing is hosted by us.",
+  ]);
+
   let githubToken;
-  try {
-    githubToken = await deviceFlow(ui);
-    ui.success("Authenticated with GitHub");
-  } catch (err) {
-    ui.error(`GitHub auth failed: ${err.message}`);
+  // gh is the only local auth path: GitHub's own CLI, so no Egregore OAuth
+  // consent screen ever. We do NOT fall back to a third-party device flow —
+  // when gh is missing we guide the user to install it and re-run.
+  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 installer.`);
     process.exit(1);
+  } else {
+    // gh isn't installed. Offer to install it + sign in right here — Enter
+    // accepts. gh is GitHub's own CLI, so there's no Egregore consent screen.
+    ui.note(ghFallbackNote(ui));
+    const cmd = ghInstallShellCommand();
+    if (cmd) {
+      const ok = await ui.confirm(`Install GitHub CLI now and sign in? (${ui.bold(cmd)})`, true);
+      if (ok) githubToken = runGhInstallAndLogin(ui, cmd);
+    }
+    if (!githubToken) {
+      ui.info("No problem — run the steps above when ready, then re-run this.");
+      process.exit(1);
+    }
   }
 
   // 2. Get user info
   const user = await getUser(githubToken);
 
-  // 3. Where — always show picker (personal first)
-  console.log("");
+  // 3. Where — we always have a gh token (the only local auth path), which
+  //    carries org read, so we can list the user's accounts and offer a picker.
+  ui.section("Pick a home", "where should this Egregore live?");
   const s = ui.spinner("Checking your GitHub accounts...");
   const orgs = await listOrgs(githubToken);
-  s.stop("");
+  s.stop("Accounts loaded");
 
   let githubOrg, isOrg;
   if (orgs.length === 0) {
     githubOrg = user.login;
     isOrg = false;
-    ui.info(`Using personal account: ${ui.bold(githubOrg)}`);
+    ui.info(`Using your personal account: ${ui.bold(githubOrg)}`);
   } else {
     const orgChoices = [{ label: user.login, description: "Personal account" }];
     for (const o of orgs) {
       orgChoices.push({ label: o.login, description: "Organization" });
     }
-    const orgChoice = await ui.choose("Where do you want to set up Egregore?", orgChoices, "Don't see your org? Grant access on the GitHub authorization page and re-run.");
+    const orgChoice = await ui.choose(
+      "Where should Egregore live?",
+      orgChoices,
+      "Don't see your org? Authorize it for your account on GitHub, then re-run.",
+    );
     githubOrg = orgChoice.label;
     isOrg = githubOrg !== user.login;
   }
@@ -300,8 +558,7 @@ async function localFounderFlow(ui, ctx = {}) {
   let isNewProject;
   if (ctx.prefilledRepo) {
     isNewProject = false;
-    console.log("");
-    ui.info(`Existing project — we'll manage ${ui.cyan(ctx.prefilledRepo.localName)} plus any others you pick.`);
+    ui.info(`${ui.green("→")} existing project — we'll manage ${ui.cyan(ctx.prefilledRepo.localName)} plus any others you pick.`);
   } else {
     const action = await ui.choose("What are you working on?", [
       { label: "Starting something new", description: "Create a project from scratch" },
@@ -311,28 +568,55 @@ async function localFounderFlow(ui, ctx = {}) {
   }
 
   // 5. Collect project info
+  ui.section("Name it", "what's this Egregore called?");
   let orgName, description, selectedRepos = [], newProjectRepo = null;
 
   if (isNewProject) {
-    const nameInput = await ui.prompt("Name your Egregore (your team or group name):");
-    orgName = nameInput || githubOrg;
-
-    const descInput = await ui.prompt("What are you building? (one line)");
-    description = descInput || "";
+    orgName = await ui.prompt("name your Egregore (team or group name)", { default: githubOrg });
+    description = await ui.prompt("what are you building? (one line)");
+
+    // Derive the egregore + memory repo names now so we can validate the
+    // optional project repo name against them before the user commits to it.
+    // Matches the final derivation at line ~395 below.
+    const slugifyRepo = (s) => s.toLowerCase()
+      .replace(/[^a-z0-9-]/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "") || "egregore";
+    const predictedRepoName = slugifyRepo(orgName);
+    const predictedMemoryRepoName = `${predictedRepoName}-memory`;
 
     // Ask about project repo
-    console.log("");
-    ui.info("Your Egregore is set up. It has its own repo for memory and config.");
-    ui.info("If you also have a code project to work on, we can create a repo for it.");
-    console.log("");
-    const projectName = await ui.prompt("Code project repo name (Enter to skip):");
-    if (projectName) {
-      newProjectRepo = projectName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    ui.note([
+      "Your Egregore gets its own repo (memory + config) in your account.",
+      "Have a code project too? Egregore can add a repo for it in your account.",
+    ]);
+
+    while (true) {
+      const projectName = await ui.prompt("code project repo name (Enter to skip)");
+      if (!projectName) {
+        newProjectRepo = null;
+        break;
+      }
+      const slug = slugifyRepo(projectName);
+      if (!slug) {
+        ui.warn("That doesn't produce a valid repo name. Try letters, numbers, and dashes.");
+        continue;
+      }
+      if (slug === predictedRepoName) {
+        ui.warn(`"${slug}" is already the name of your Egregore repo. Pick a different name.`);
+        ui.info(`  ${ui.dim("suggestion:")} ${ui.cyan(`${slug}-app`)}`);
+        continue;
+      }
+      if (slug === predictedMemoryRepoName) {
+        ui.warn(`"${slug}" collides with your memory repo. Pick a different name.`);
+        continue;
+      }
+      newProjectRepo = slug;
+      break;
     }
   } else {
     // "Existing project"
-    const nameInput = await ui.prompt(`What should we call this Egregore? [${githubOrg}]:`);
-    orgName = nameInput || githubOrg;
+    orgName = await ui.prompt("what should we call this Egregore?", { default: githubOrg });
     description = "";
 
     // Auto-adopt the user's current repo if it's under the chosen GitHub owner.
@@ -412,7 +696,7 @@ async function localFounderFlow(ui, ctx = {}) {
       s1.stop(`${githubOrg}/${repoName} already has Egregore set up`);
       console.log("");
       ui.info("To join it:");
-      ui.info(`  ${ui.bold(`npx -y egregore-init@latest join ${githubOrg}/${repoName}`)}`);
+      ui.info(`  ${ui.bold(joinCommand(githubOrg, repoName))}`);
       console.log("");
       ui.info("To set up a different one, choose a different team name.");
       process.exit(0);
@@ -501,8 +785,11 @@ async function localFounderFlow(ui, ctx = {}) {
     report_url: "https://xgksfrirtdumacvmfkzj.supabase.co",
     report_key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Inhna3NmcmlydGR1bWFjdm1ma3pqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzA5OTA1ODksImV4cCI6MjA4NjU2NjU4OX0.1UWNgER6nQazrayly1KDrswClURUkGKxeirZg5L8uk4",
   };
-  try {
-    await putFileContent(
+  // Joiners resolve the org by reading egregore.json from the remote — if
+  // this push silently fails (observed: transient failure right after
+  // template generation), the org is unjoinable and the founder never knows.
+  const configPushed = await retryAsync(async () => {
+    const { status } = await putFileContent(
       githubToken,
       githubOrg,
       repoName,
@@ -510,19 +797,28 @@ async function localFounderFlow(ui, ctx = {}) {
       JSON.stringify(egreConfig, null, 2) + "\n",
       `Configure egregore for ${orgName}`,
     );
-  } catch {}
+    return status < 300;
+  });
+  if (!configPushed) {
+    ui.warn(`Could not publish egregore.json to ${githubOrg}/${repoName} — teammates can't join until it's there.`);
+    ui.info(`  Re-run this installer to retry, or push egregore.json from the cloned repo.`);
+  }
 
   // 8b. Register org with Egregore API (non-blocking — local mode works without it)
   //     Respects DO_NOT_TRACK (https://consult.gov.uk/digital-communications/online-advertising/supporting_documents/DNT%20standard%20v10.pdf)
   if (!process.env.DO_NOT_TRACK && !process.env.EGREGORE_NO_TELEMETRY) {
     try {
       const api = new EgregoreAPI();
-      await api.registerOrg(githubToken, { org_name: orgName, github_org: githubOrg, slug });
+      await api.registerOrg(githubToken, {
+        org_name: orgName,
+        github_org: githubOrg,
+        slug,
+      });
     } catch {}
   }
 
   // 9. Init memory dirs on remote (so joiners get the structure)
-  const memDirs = ["people", "handoffs", "knowledge/decisions", "knowledge/patterns", "knowledge/findings", "quests", "wraps"];
+  const memDirs = ["people", "invites", "handoffs", "knowledge/questions", "knowledge/decisions", "knowledge/patterns", "knowledge/findings", "quests", "wraps"];
   for (const d of memDirs) {
     try {
       await putFileContent(githubToken, githubOrg, memoryRepoName, `${d}/.gitkeep`, "", `Initialize ${d}`);
@@ -539,10 +835,23 @@ async function localFounderFlow(ui, ctx = {}) {
   const totalSteps = 6 + selectedRepos.length;
   configureGitCredentials(githubToken);
 
+  ui.section("Install", "cloning repos, linking memory, wiring credentials");
+
   ui.step(1, totalSteps, "Cloning egregore...");
   cloneRepo(forkUrl, egregoreDir, githubToken, ui, "egregore");
   setGitIdentity(egregoreDir, user);
   ensureDevelop(egregoreDir);
+  // ensureDevelop only creates develop on the REMOTE (git branch, no checkout),
+  // so the clone is still on main. The egregore operates on develop, so switch
+  // to it now — otherwise local overlays (the codex runtime) get committed to
+  // main and are orphaned when session-start later checks out develop.
+  try {
+    execFileSync("git", ["-C", egregoreDir, "checkout", "develop"], { stdio: "pipe" });
+  } catch {
+    try {
+      execFileSync("git", ["-C", egregoreDir, "checkout", "-b", "develop", "origin/develop"], { stdio: "pipe" });
+    } catch {}
+  }
 
   ui.step(2, totalSteps, "Cloning shared memory...");
   cloneRepo(memoryUrl, memoryDir, githubToken, ui, "memory");
@@ -564,19 +873,43 @@ async function localFounderFlow(ui, ctx = {}) {
   fs.writeFileSync(path.join(egregoreDir, "egregore.json"), JSON.stringify(egreConfig, null, 2) + "\n");
 
   // 14. "What should we call you?" + write state
-  console.log("");
-  const displayName = await ui.prompt(`What should we call you? [${user.login}]:`);
+  ui.section("Your name", "this is how teammates will see you in handoffs");
+  const displayName = await ui.prompt("what should we call you?", { default: user.login });
+  const memberRole = await ensureInstallerMemberRole(
+    { usage_type: "founder_group", member_role: ctx.memberRole },
+    {},
+    ui
+  );
 
+  // 14b. Write onboarding-shortcut state so the /onboarding skill can skip
+  //      ORIENT + INVITE-offer (the installer already collected display_name
+  //      and ran the invite flow). See .claude/skills/onboarding/SKILL.md
+  //      "Pre-captured check" blocks.
+  const slugifiedName = (displayName || user.login).toLowerCase().replace(/\s+/g, "-");
   const state = {
     github_username: user.login,
     github_name: user.name,
     display_name: displayName || user.login,
+    name: slugifiedName,
+    member_role: memberRole,
     email: user.email,
     onboarding_complete: false,
     usage_type: "founder_group",
     org_setup: true,
     github_configured: true,
     workspace_ready: true,
+    preferred_runtime: preferredRuntime,
+    // Pre-captured onboarding signals. Invite flag is set later in step 18
+    // after the user's answer; default to undefined here so the skill knows
+    // to wait, then the installer mutates this block on invite completion.
+    onboarding: {
+      phase: "orient",
+      started_at: new Date().toISOString(),
+      installer_captured: true,
+      role: "founder",
+      member_role: memberRole,
+    },
+    profile_fields_collected: ["name", "role"],
   };
   fs.writeFileSync(path.join(egregoreDir, ".egregore-state.json"), JSON.stringify(state, null, 2) + "\n");
 
@@ -625,14 +958,73 @@ async function localFounderFlow(ui, ctx = {}) {
     }
   }
 
-  // 17. Register instance + shell alias
+  const codexRuntime = installCodexRuntime(egregoreDir);
+  reportCodexRuntimeSummary(codexRuntime, ui);
+
+  // 16b. Commit the Codex runtime into the repo so it's TRACKED — symmetric
+  //      with .claude/ (which ships in the template). An untracked overlay can
+  //      be lost to later git operations, and joiners would never get it. This
+  //      way every Egregore supports BOTH assistants, persistently and for the
+  //      whole team: pick Claude Code or Codex, now or later, and it just works.
+  try {
+    const toCommit = Array.isArray(codexRuntime.files) ? [...codexRuntime.files] : [];
+    if (fs.existsSync(path.join(egregoreDir, ".agents", "skills"))) toCommit.push(".agents/skills");
+    if (toCommit.length) {
+      execFileSync("git", ["add", "--", ...toCommit], { cwd: egregoreDir, stdio: "pipe" });
+      run('git commit -m "Add Codex runtime so this Egregore supports both assistants"', { cwd: egregoreDir });
+      run("git push", { cwd: egregoreDir });
+    }
+  } catch {}
+
+  // 17. Register instance + install launcher binary
   ui.step(5 + selectedRepos.length, totalSteps, "Registering instance...");
-  registerInstance(repoName, orgName, egregoreDir);
-  const alias = await installShellAlias(egregoreDir, ui);
+  registerInstance(repoName, orgName, egregoreDir, preferredRuntime);
+  const alias = await installLauncherBinary(egregoreDir, ui);
+
+  const telegramResult = await maybeSetupTelegramGroup(ui, {
+    egregoreDir,
+    githubToken,
+    githubOrg,
+    repoName,
+    egreConfig,
+    statePath: path.join(egregoreDir, ".egregore-state.json"),
+  });
+
+  // 18. Optional invite — picker for org members, text fallback otherwise.
+  ui.section("Bring someone in", "Egregore shines when it's shared");
+
+  let invUsername = "";
+  if (isOrg) {
+    const memberSpin = ui.spinner("Loading org members...");
+    const members = await listOrgMembers(githubToken, githubOrg);
+    memberSpin.stop(members.length > 0 ? `Loaded ${members.length} members` : "No visible members");
+
+    // Filter out the current user — they can't invite themselves.
+    const pickable = members
+      .filter((m) => m.login !== user.login)
+      .slice(0, 20);
+
+    if (pickable.length > 0) {
+      const choices = [
+        { label: "Skip — work solo for now", description: "I can always /invite later" },
+        ...pickable.map((m) => ({ label: m.login, description: `@${githubOrg} member` })),
+        { label: "Type a username", description: "invite someone not in the list" },
+      ];
+      const picked = await ui.choose("who should we invite?", choices);
+      if (picked.label === "Skip — work solo for now") {
+        invUsername = "";
+      } else if (picked.label === "Type a username") {
+        invUsername = await ui.prompt("GitHub username");
+      } else {
+        invUsername = picked.label;
+      }
+    } else {
+      invUsername = await ui.prompt("teammate's GitHub username (or Enter to skip)");
+    }
+  } else {
+    invUsername = await ui.prompt("teammate's GitHub username (or Enter to skip)");
+  }
 
-  // 18. Optional invite
-  console.log("");
-  const invUsername = await ui.prompt("Invite a teammate? Enter their GitHub username (or press Enter to skip):");
   if (invUsername) {
     const invSpin = ui.spinner(`Inviting ${invUsername}...`);
     try {
@@ -657,36 +1049,106 @@ async function localFounderFlow(ui, ctx = {}) {
       const invPersonFile = path.join(memoryDir, "people", `${invUsername}.md`);
       if (!fs.existsSync(invPersonFile)) {
         fs.writeFileSync(invPersonFile, invPersonContent);
-        try {
-          run("git add -A", { cwd: memoryDir });
-          run(`git commit -m "Invite ${invUsername}"`, { cwd: memoryDir });
-          run("git push", { cwd: memoryDir });
-        } catch {}
       }
+      const fallbackCommand = joinCommand(githubOrg, repoName);
+      const inviteArtifact = writeInviteArtifact(memoryDir, {
+        inviter: user.login,
+        invitee: invUsername,
+        githubOrg,
+        repoName,
+        memoryRepo: `https://github.com/${githubOrg}/${memoryRepoName}.git`,
+        managedRepos: selectedRepos,
+        fallbackCommand,
+        telegramGroupLink: egreConfig.telegram_group_link || "",
+        delivery: "copyable_share_block",
+      });
+      commitMemoryInvite(memoryDir, [invPersonFile, inviteArtifact], invUsername);
 
       invSpin.stop(`Invited ${invUsername}`);
-      console.log("");
-      ui.info(`Tell them to run:`);
-      ui.commandBox("command", `npx -y egregore-init@latest join ${githubOrg}/${repoName}`);
+      ui.info("send this to them:");
+      const shareLines = [fallbackCommand];
+      if (egreConfig.telegram_group_link) {
+        shareLines.push(`Telegram: ${egreConfig.telegram_group_link}`);
+      }
+      ui.card("share", shareLines);
     } catch (err) {
       invSpin.fail(`Could not invite ${invUsername}: ${err.message}`);
     }
   }
 
-  // 19. Done
-  console.log("");
-  ui.success(`Egregore is ready for ${ui.bold(orgName)}`);
-  console.log("");
-  ui.info("Your workspace:");
-  ui.info(`  ${ui.cyan(`./${repoName}/`)}  — Your Egregore instance`);
-  ui.info(`  ${ui.cyan(`./${memoryRepoName}/`)} — Shared knowledge`);
-  for (const entry of selectedRepos) {
-    const mrName = typeof entry === "string" ? entry : entry.name;
-    ui.info(`  ${ui.cyan(`./${mrName}/`)}  — Managed repo`);
+  // 18b. Record invite outcome in state so the /onboarding skill knows to
+  //      skip the INVITE-offer step. See SKILL.md "Pre-captured check".
+  {
+    const statePath = path.join(egregoreDir, ".egregore-state.json");
+    try {
+      const cur = JSON.parse(fs.readFileSync(statePath, "utf-8"));
+      cur.onboarding = cur.onboarding || {};
+      cur.onboarding.invite_skipped = !invUsername;
+      cur.onboarding.invite_handled_by = "installer";
+      cur.onboarding.phase = "complete";
+      cur.onboarding.completed_at = cur.onboarding.completed_at || new Date().toISOString();
+      cur.onboarding.role = cur.onboarding.role || "founder";
+      cur.onboarding_complete = true;
+      cur.profile_fields_collected = Array.isArray(cur.profile_fields_collected)
+        ? Array.from(new Set([...cur.profile_fields_collected, "name"]))
+        : ["name"];
+      fs.writeFileSync(statePath, JSON.stringify(cur, null, 2) + "\n");
+      ensurePersonOnboardingWitness(memoryDir, cur);
+    } catch {}
   }
-  console.log("");
-  ui.info(`Next: open a ${ui.bold("new terminal")} and type ${ui.bold(alias.aliasName)} to start.`);
-  console.log("");
+
+  // 19. Done — summary screen (alt-screen) if we can, inline otherwise.
+  //     Either way it doubles as the Insight-rendering moment that lets
+  //     /onboarding skip ORIENT on first Claude session.
+  const workspaces = [
+    { label: `./${repoName}/`, description: "your Egregore instance" },
+    { label: `./${memoryRepoName}/`, description: "shared knowledge" },
+    ...selectedRepos.map((entry) => {
+      const mrName = typeof entry === "string" ? entry : entry.name;
+      return { label: `./${mrName}/`, description: "managed repo" };
+    }),
+  ];
+  const assistantName = preferredRuntime === "codex" ? "Codex" : "Claude Code";
+  const setupSummary = {
+    workspace: "created",
+    invite: invUsername ? `sent to ${invUsername}` : "skipped",
+    telegram: telegramResult.groupLink
+      ? "connected"
+      : telegramResult.setup
+        ? "bot added; no join link saved"
+        : "skipped",
+    assistant: assistantName,
+    command: "run egregore anytime",
+  };
+
+  if (!ctx.noScreens && ui.canShowScreens()) {
+    const result = await ui.summaryScreen({ orgName, workspaces, setup: setupSummary });
+    if (result === "escape") {
+      // User pressed esc: skip auto-launch, just return to shell.
+      ctx.noAutolaunch = true;
+    }
+  } else {
+    ui.section("You're done", `Egregore is ready for ${ui.bold(orgName)}`);
+    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("");
+    for (const ws of workspaces) {
+      ui.info(`${ui.green("●")} ${ui.cyan(ws.label)}   ${ui.dim(ws.description)}`);
+    }
+    ui.note([
+      "Every session leaves traces — decisions, patterns, context.",
+      "Egregore makes those traces persistent and shared.",
+      "",
+      "You do your work. When you're done, you hand off what you",
+      "learned. The next session — yours or someone else's — starts",
+      "smarter.",
+    ]);
+  }
+
+  await launchOrInstruct(egregoreDir, alias, ui, ctx);
 }
 
 // ── Flow 2: Join (local mode) ──────────────────────────────────────
@@ -714,22 +1176,43 @@ function parseJoinTarget(arg) {
   return { orgLogin: parts[0], explicitRepo: parts[1] || null };
 }
 
+function normalizeMemoryUrl(memoryRepo, owner, fallbackName) {
+  if (memoryRepo && /^https?:\/\//i.test(memoryRepo)) return memoryRepo;
+  if (memoryRepo && /^git@/i.test(memoryRepo)) return memoryRepo;
+  const repoName = memoryRepo || fallbackName;
+  return `https://github.com/${owner}/${repoName}.git`;
+}
+
 async function localJoinFlow(orgArg, ui, ctx = {}) {
   const { orgLogin, explicitRepo } = parseJoinTarget(orgArg);
   if (!orgLogin) {
-    ui.error("Usage: npx create-egregore join <org>[/<repo>]");
+    ui.error("Usage: npx -y create-egregore@latest join <org>[/<repo>]");
     process.exit(1);
   }
 
-  // 1. GitHub auth — OAuth with repo:invite scope (narrow: just invitation acceptance)
-  ui.info(`Joining ${ui.bold(orgLogin)}. First, sign in with GitHub.\n`);
+  // 1. GitHub auth — prefer gh CLI. If gh is installed but logged out, run
+  //    gh auth login. Only no-gh machines use the device fallback.
+  ui.info(`Joining ${ui.bold(orgLogin)}.`);
   let githubToken;
-  try {
-    githubToken = await deviceFlow(ui, { mode: "join" });
-    ui.success("Authenticated with GitHub");
-  } catch (err) {
-    ui.error(`GitHub auth failed: ${err.message}`);
+  const ghAuth = tryGhAuthOrLogin(ui, { mode: "join" });
+  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 join command.`);
     process.exit(1);
+  } else {
+    ui.note(ghFallbackNote(ui));
+    const cmd = ghInstallShellCommand();
+    if (cmd) {
+      const ok = await ui.confirm(`Install GitHub CLI now and sign in? (${ui.bold(cmd)})`, true);
+      if (ok) githubToken = runGhInstallAndLogin(ui, cmd);
+    }
+    if (!githubToken) {
+      ui.info("No problem — run the steps above when ready, then re-run this.");
+      process.exit(1);
+    }
   }
 
   // 2. Get user info
@@ -741,111 +1224,70 @@ async function localJoinFlow(orgArg, ui, ctx = {}) {
   await acceptPendingInvitations(githubToken, orgLogin, ui);
   s1.stop("Invitations accepted");
 
-  // 4. Determine repo name
+  // 4. Resolve egregore.json before cloning. The shared install() helper owns
+  //    all local filesystem setup after this point.
   const repoName = explicitRepo || "egregore";
-
-  // 5. Clone repos using git credentials (SSH keys / gh CLI / credential helper)
-  //    The OAuth token only has repo:invite scope — cloning uses the joiner's own git setup.
-  const base = ctx.targetDir || process.cwd();
-  const egregoreDir = path.join(base, repoName);
-
-  console.log("");
-  const s2 = ui.spinner(`Cloning ${orgLogin}/${repoName}...`);
-  if (cloneWithFallback(`https://github.com/${orgLogin}/${repoName}.git`, egregoreDir)) {
-    s2.stop(`Cloned ${repoName}`);
-  } else {
-    s2.fail(`Could not clone ${orgLogin}/${repoName}`);
-    ui.error("Make sure you have git credentials set up (SSH keys or gh auth login).");
-    ui.error("Also verify the org admin has set up Egregore and invited you.");
-    process.exit(1);
-  }
-  setGitIdentity(egregoreDir, user);
-  ensureDevelop(egregoreDir);
-
-  // 6. Read egregore.json from local clone
-  const configPath = path.join(egregoreDir, "egregore.json");
-  if (!fs.existsSync(configPath)) {
-    ui.error("The repo has no egregore.json. Ask the admin to set up first.");
-    process.exit(1);
-  }
+  const s2 = ui.spinner(`Reading ${orgLogin}/${repoName}/egregore.json...`);
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-  } catch {
-    ui.error("Invalid egregore.json");
+    const raw = await getFileContent(githubToken, orgLogin, repoName, "egregore.json");
+    if (!raw) throw new Error("missing");
+    config = JSON.parse(raw);
+    s2.stop("Resolved Egregore config");
+  } catch (err) {
+    s2.fail("Could not read egregore.json");
+    ui.error(`Make sure ${orgLogin}/${repoName} exists and you accepted the GitHub invitation.`);
+    ui.info(`Ask the admin to resend: ${joinCommand(orgLogin, repoName)}`);
     process.exit(1);
   }
   ui.success(`Found ${ui.bold(config.org_name || orgLogin)}`);
 
   const orgName = config.org_name || orgLogin;
-  const memoryRepoName = config.memory_repo
-    ? config.memory_repo.split("/").pop().replace(/\.git$/, "")
-    : `${orgLogin}-memory`;
   const managedRepos = config.repos || [];
-
-  // 7. Clone memory + managed repos
-  const memoryUrl = config.memory_repo || `https://github.com/${orgLogin}/${memoryRepoName}.git`;
-  const memoryDir = path.join(base, memoryRepoName);
-
-  const totalSteps = 4 + managedRepos.length;
-  // Store the invite token for later use (invitation acceptance, not cloning)
-  const inviteToken = githubToken;
-
-  // Clone memory using SSH-first fallback (same as main repo)
-  ui.step(1, totalSteps, "Cloning shared memory...");
-  if (cloneWithFallback(memoryUrl, memoryDir)) {
-    ui.success("Cloned memory");
-  } else {
-    ui.warn("Could not clone memory repo — you may not have access yet.");
+  const skipRepos = new Set();
+  if (ctx.prefilledRepo && Array.isArray(managedRepos)) {
+    for (const entry of managedRepos) {
+      const name = repoEntryName(entry);
+      if (name && name === ctx.prefilledRepo.name) skipRepos.add(name);
+    }
   }
-  setGitIdentity(memoryDir, user);
-
-  // Symlink
-  ui.step(2, totalSteps, "Linking memory...");
-  createSymlink(egregoreDir, memoryDir, ui);
-
-  // Write .env — store invite token for session-start invitation checks
-  ui.step(3, totalSteps, "Writing credentials...");
-  fs.writeFileSync(path.join(egregoreDir, ".env"), `GITHUB_TOKEN=${inviteToken}\n`, { mode: 0o600 });
-  ui.success("Credentials saved");
-
-  // "What should we call you?" + write state
-  console.log("");
-  const displayName = await ui.prompt(`What should we call you? [${user.login}]:`);
-
-  const state = {
+  const memoryUrl = normalizeMemoryUrl(config.memory_repo, orgLogin, `${repoName}-memory`);
+  const installData = {
+    fork_url: `https://github.com/${orgLogin}/${repoName}.git`,
+    memory_url: memoryUrl,
+    github_token: githubToken,
+    org_name: orgName,
+    github_org: orgLogin,
     github_username: user.login,
     github_name: user.name,
-    display_name: displayName || user.login,
-    email: user.email,
-    onboarding_complete: false,
+    github_email: user.email,
+    slug: config.slug || orgLogin,
+    repos: managedRepos,
+    repo_name: repoName,
+    telegram_group_link: config.telegram_group_link,
     usage_type: "joiner_group",
-    org_setup: true,
-    github_configured: true,
-    workspace_ready: true,
+    onboarding_role: "joiner",
+    invite_handled_by: "installer",
   };
-  fs.writeFileSync(path.join(egregoreDir, ".egregore-state.json"), JSON.stringify(state, null, 2) + "\n");
-
-  // Register + alias
-  ui.step(4, totalSteps, "Registering instance...");
-  registerInstance(repoName, orgName, egregoreDir);
-  const alias = await installShellAlias(egregoreDir, ui);
 
-  // Clone managed repos using SSH-first fallback
-  for (let i = 0; i < managedRepos.length; i++) {
-    const entry = managedRepos[i];
-    const mrName = typeof entry === "string" ? entry : entry.name;
-    ui.step(5 + i, totalSteps, `Cloning ${mrName}...`);
-    const repoDir = path.join(base, mrName);
-    if (cloneWithFallback(`https://github.com/${orgLogin}/${mrName}.git`, repoDir)) {
-      setGitIdentity(repoDir, user);
-      ui.success(`Cloned ${mrName}`);
-    } else {
-      ui.warn(`Could not clone ${mrName} — you may not have access yet.`);
-    }
+  try {
+    await install(installData, ui, ctx.targetDir, {
+      noAutolaunch: ctx.noAutolaunch,
+      noScreens: ctx.noScreens,
+      skipRepos,
+      flowVariant: ctx.flowVariant,
+      runtime: ctx.runtime,
+    });
+  } catch (err) {
+    ui.error(`Install failed: ${err.message}`);
+    process.exit(1);
   }
 
-  // 12. Check for welcome note
+  const base = ctx.targetDir || process.cwd();
+  const egregoreDir = path.join(base, repoName);
+  const memoryDir = path.join(base, memoryUrl.split("/").pop().replace(/\.git$/, ""));
+
+  // 5. Check for welcome note after install() has cloned and linked memory.
   const welcomeFile = path.join(memoryDir, "people", `${user.login}.md`);
   if (fs.existsSync(welcomeFile)) {
     try {
@@ -861,27 +1303,12 @@ async function localJoinFlow(orgArg, ui, ctx = {}) {
     } catch {}
   }
 
-  // 13. Show Telegram group link if configured
+  // 6. Show Telegram group link if configured
   if (config.telegram_group_link) {
     console.log("");
     ui.info("Join the team's Telegram group:");
     ui.info(`  ${ui.cyan(config.telegram_group_link)}`);
   }
-
-  // 14. Done
-  console.log("");
-  ui.success(`Joined ${ui.bold(orgName)}`);
-  console.log("");
-  ui.info("Your workspace:");
-  ui.info(`  ${ui.cyan(`./${repoName}/`)}  — Egregore instance`);
-  ui.info(`  ${ui.cyan(`./${memoryRepoName}/`)} — Shared knowledge`);
-  for (const entry of managedRepos) {
-    const mrName = typeof entry === "string" ? entry : entry.name;
-    ui.info(`  ${ui.cyan(`./${mrName}/`)}  — Managed repo`);
-  }
-  console.log("");
-  ui.info(`Next: open a ${ui.bold("new terminal")} and type ${ui.bold(alias.aliasName)} to start.`);
-  console.log("");
 }
 
-module.exports = { localFounderFlow, localJoinFlow, parseJoinTarget, addCollaborator, getUser, repoExists, createRepo, waitForRepo };
+module.exports = { localFounderFlow, localJoinFlow, parseJoinTarget, addCollaborator, getUser, repoExists, createRepo, waitForRepo, retryAsync, ghFallbackNote };