create-egregore 0.18.18 → 0.19.2

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.5.27
+// egregore-launcher-version: 0.6.0
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -30,7 +30,7 @@ const https = require("node:https");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.5.27";
+const VERSION = "0.6.0";
 const REGISTRY = path.join(os.homedir(), ".egregore", "instances.json");
 const DEFAULT_FILE = path.join(os.homedir(), ".egregore", "default");
 const PUBLIC_NPX_PACKAGE = "create-egregore";
@@ -424,7 +424,7 @@ function runtimePickerLines(inst, runtimes, stored, cursor) {
   const labelWidth = Math.max(...runtimes.map((r) => runtimeLabel(r).length));
   const lines = [
     "",
-    `  ${DIM}↑↓${RESET} navigate · ${DIM}enter${RESET} select · ${DIM}1-${runtimes.length}${RESET} quick select · ${DIM}esc${RESET} cancel`,
+    `  ${DIM}↑↓${RESET} navigate · ${DIM}enter${RESET} select · ${DIM}1-${runtimes.length}${RESET} quick select · ${DIM}q${RESET} cancel`,
     `  ${CYAN}◆${RESET} ${BOLD}Launch ${title} with which harness?${RESET}`,
     "",
   ];
@@ -494,7 +494,9 @@ function pickRuntimeInteractive(inst, runtimes, stored) {
         cleanup();
         process.exit(130);
       }
-      if (key.name === "escape" || key.name === "q") return finish(null);
+      // Esc never quits (it reads as "back", and there's nowhere back to go
+      // from here) — q is the only cancel key besides Ctrl+C.
+      if (key.name === "q") return finish(null);
       if (key.name === "up" || (key.ctrl && key.name === "p") || key.name === "k") {
         cursor = (cursor - 1 + runtimes.length) % runtimes.length;
         render();
@@ -832,10 +834,9 @@ function cmdHelp() {
     `    ${DIM}n / +${RESET}       create a new Egregore`,
     `    ${DIM}u${RESET}           set selected as default`,
     `    ${DIM}i${RESET}           invite a GitHub user to selected instance`,
-    `    ${DIM}r${RESET}           remove selected (with confirm)`,
-    `    ${DIM}p${RESET}           prune entries with missing paths (with confirm)`,
+    `    ${DIM}d${RESET}           delete selected entry (offers cleanup of ${RED}✗${RESET} missing ones)`,
     `    ${DIM}?${RESET}           toggle help overlay`,
-    `    ${DIM}q / esc${RESET}     quit browser`,
+    `    ${DIM}q${RESET}           quit browser (esc goes back — it never quits)`,
     ``,
     `  ${BOLD}REGISTRY${RESET}`,
     `    ${DIM}instances:${RESET} ~/.egregore/instances.json`,
@@ -1463,7 +1464,7 @@ function renderRuntimePanel({ inst, cursor, width, height }) {
   }
 
   lines.push(emptyBoxLine(innerWidth, margin));
-  lines.push(boxLine(`${DIM}↑↓ navigate · enter select · 1-${runtimes.length} quick select · esc back · q quit${RESET}`, innerWidth, margin));
+  lines.push(boxLine(`${DIM}↑↓ navigate · enter select · 1-${runtimes.length} quick select · ← back · q quit${RESET}`, innerWidth, margin));
   lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
   return lines;
 }
@@ -1482,6 +1483,15 @@ async function browser(args = {}) {
     return numberedPicker(registry, args.runtimeOverride);
   }
 
+  // Entries whose directory is gone are dead registry rows. They stay listed
+  // (marked ✗ missing) so the problem is visible in place — cleanup is offered
+  // through `d`, never done automatically. Cached per session; refreshed after
+  // every registry mutation instead of stat-ing on each keypress render.
+  let stalePaths = new Set(registry.filter((e) => !fs.existsSync(e.path)).map((e) => e.path));
+  const refreshStale = () => {
+    stalePaths = new Set(registry.filter((e) => !fs.existsSync(e.path)).map((e) => e.path));
+  };
+
   // State
   const state = {
     filter: "",
@@ -1493,7 +1503,7 @@ async function browser(args = {}) {
     runtimeCursor: 0,
     cursor: initialCursorForCwd(registry),
     showHelp: false,
-    modal: null, // { type: "remove" | "prune", onYes, onNo }
+    modal: null, // { type: "remove" | "sweep", onYes, onNo }
     tick: 0,
     message: null, // ephemeral info line (e.g. "default set to X")
     messageKind: "info", // "info" | "success" | "warn"
@@ -1585,7 +1595,10 @@ async function browser(args = {}) {
     out.push(ANSI.clearLine + "\n");
 
     // Layout: list takes top 60%, preview takes rest, footer is last 2 lines
-    const footerRows = 2;
+    // (3 while stale entries exist — the cleanup notice gets its own row so
+    // the layout doesn't jump when modals or messages come and go).
+    const staleCount = stalePaths.size;
+    const footerRows = staleCount > 0 ? 3 : 2;
     const usedRows = heroLines.length + 1;
     const availableRows = Math.max(8, h - usedRows - footerRows - 2);
     const listRows = Math.max(4, Math.floor(availableRows * 0.48));
@@ -1631,13 +1644,21 @@ async function browser(args = {}) {
       void origIdx;
       const isCursor = idx === state.cursor;
       const isDefault = e.slug === def;
+      const isMissing = stalePaths.has(e.path);
       const cursorMark = isCursor ? `${CYAN}❯${RESET}` : " ";
       const defMark = isDefault ? `${GREEN}●${RESET}` : " ";
       const slug = isCursor
         ? `${BOLD}${CYAN}${pad(e.slug, slugW)}${RESET}`
-        : (isDefault ? `${BOLD}${pad(e.slug, slugW)}${RESET}` : pad(e.slug, slugW));
-      const name = pad(e.name || "", nameW);
-      const pathDim = `${DIM}${truncate(e.path, Math.max(0, listAvail - slugW - nameW - 10))}${RESET}`;
+        : (isDefault
+          ? `${BOLD}${pad(e.slug, slugW)}${RESET}`
+          : (isMissing ? `${DIM}${pad(e.slug, slugW)}${RESET}` : pad(e.slug, slugW)));
+      const name = isMissing && !isCursor
+        ? `${DIM}${pad(e.name || "", nameW)}${RESET}`
+        : pad(e.name || "", nameW);
+      const pathAvail = Math.max(0, listAvail - slugW - nameW - 10);
+      const pathDim = isMissing
+        ? `${RED}✗${RESET} ${DIM}${truncate(e.path, Math.max(8, pathAvail - 12))}${RESET} ${RED}(missing)${RESET}`
+        : `${DIM}${truncate(e.path, pathAvail)}${RESET}`;
       const line = ` ${cursorMark} ${defMark}  ${slug}  ${name}  ${pathDim}`;
       out.push(M + " ".repeat(listPad - 3) + line + ANSI.clearLine + "\n");
     }
@@ -1661,7 +1682,9 @@ async function browser(args = {}) {
       // value to blockWidth-15 so every line's right edge lands two cols inside
       // the box border, level with the box inner content (gutter+blockWidth-2).
       const valW = Math.max(16, blockWidth - 15);
-      previewLines.push(`  ${label("path")} ${truncate(selected.path, valW)}`);
+      previewLines.push(stalePaths.has(selected.path)
+        ? `  ${label("path")} ${RED}✗${RESET} ${truncate(selected.path, Math.max(8, valW - 12))} ${RED}(missing)${RESET}`
+        : `  ${label("path")} ${truncate(selected.path, valW)}`);
       if (pv.org) previewLines.push(`  ${label("org")} ${truncate(`${pv.org} ${DIM}(${pv.githubOrg || "?"})${RESET}`, valW)}`);
       if (pv.branch) previewLines.push(`  ${label("branch")} ${BOLD}${pv.branch}${RESET}`);
       if (pv.lastCommit) previewLines.push(`  ${label("last")} ${DIM}${truncate(pv.lastCommit, valW)}${RESET}`);
@@ -1690,32 +1713,54 @@ async function browser(args = {}) {
     // Divider
     out.push(DIM + M + "─".repeat(blockWidth) + RESET + ANSI.clearLine + "\n");
 
-    // Footer
+    // Notice row — persistent while dead entries exist, quiet otherwise. The
+    // row is reserved either way (footerRows above) so toggling modals/filter
+    // doesn't shift the layout.
+    if (staleCount > 0) {
+      const noticeIdle = !state.modal && !state.filterMode && !state.inviteMode;
+      const noun = staleCount === 1 ? "entry points to a missing folder" : "entries point to missing folders";
+      out.push(noticeIdle
+        ? `${M}  ${YELLOW}!${RESET} ${staleCount} ${noun} — ${BOLD}d${RESET} ${DIM}to clean up${RESET}${ANSI.clearLine}\n`
+        : ANSI.clearLine + "\n");
+    }
+
+    // Footer — a status band in the banner's accent color (the terminal's
+    // cyan slot) anchors the keys; the plain dim strip was easy to miss.
+    // Band color doubles as a mode signal: accent = browsing, yellow = a
+    // question needs answering, green = success flash. Input states
+    // (filter, invite) stay unbanded so the caret keeps its contrast.
+    // Content on the band is fg-black with BOLD/UNBOLD only — a RESET
+    // mid-line would kill the background fill.
+    const UNBOLD = E(22);
+    const band = (content, bg) => colorOn
+      ? `${E(bg)}${E(30)}${pad(`  ${content}`, blockWidth)}${RESET}${ANSI.clearLine}`
+      : `  ${stripAnsi(content)}${ANSI.clearLine}`;
+    const key = (k, label) => `${BOLD}${k}${UNBOLD} ${label}`;
     let footer;
     if (state.modal) {
       const m = state.modal;
       const prompt = m.type === "remove"
-        ? `remove ${BOLD}${m.inst.slug}${RESET}? ${DIM}[y/N]${RESET}`
-        : `prune ${BOLD}${m.count}${RESET} stale entries? ${DIM}[y/N]${RESET}`;
-      footer = `  ${YELLOW}?${RESET} ${prompt}${ANSI.clearLine}`;
+        ? `remove ${BOLD}${m.inst.slug}${UNBOLD}${m.missing ? " (folder missing)" : ""}? [y/N]`
+        : `remove ${BOLD}${m.count}${UNBOLD} ${m.count === 1 ? "entry" : "entries"} with missing folders? [y/N]`;
+      footer = band(`? ${prompt}`, 43);
     } else if (state.filterMode) {
       footer = `  ${DIM}typing filter · enter/esc to exit filter mode${RESET}${ANSI.clearLine}`;
     } else if (state.inviteMode) {
       const target = state.inviteInst?.slug || "selected";
       footer = `  ${CYAN}/invite${RESET} ${DIM}${target}:${RESET} ${state.inviteUsername}${CYAN}▌${RESET} ${DIM}enter send · esc cancel${RESET}${ANSI.clearLine}`;
     } else if (state.showHelp) {
-      footer = `  ${DIM}? toggles this hint · q quits${RESET}${ANSI.clearLine}`;
+      footer = band(`${key("?", "toggles this hint")}  ${key("q", "quits")}`, 46);
     } else if (state.message && Date.now() < state.messageUntil) {
-      const kindColor = state.messageKind === "success" ? GREEN : state.messageKind === "warn" ? YELLOW : CYAN;
-      footer = `  ${kindColor}●${RESET} ${state.message}${ANSI.clearLine}`;
+      const bg = state.messageKind === "success" ? 42 : state.messageKind === "warn" ? 43 : 46;
+      footer = band(`● ${stripAnsi(state.message)}`, bg);
     } else {
       footer = blockWidth < 96
-        ? `  ${DIM}↑↓${RESET} nav  ${DIM}enter${RESET} select  ${DIM}n/+${RESET} new  ${DIM}i${RESET} invite  ${DIM}?${RESET} help  ${DIM}q${RESET} quit${ANSI.clearLine}`
-        : `  ${DIM}↑↓${RESET} nav  ${DIM}enter${RESET} select  ${DIM}n/+${RESET} new  ${DIM}/${RESET} filter  ${DIM}i${RESET} invite  ${DIM}u${RESET} default  ${DIM}r${RESET} rm  ${DIM}p${RESET} prune  ${DIM}?${RESET} help  ${DIM}q${RESET} quit${ANSI.clearLine}`;
+        ? band(`${key("↑↓", "nav")}  ${key("enter", "select")}  ${key("n/+", "new")}  ${key("i", "invite")}  ${key("d", "delete")}  ${key("?", "help")}  ${key("q", "quit")}`, 46)
+        : band(`${key("↑↓", "nav")}  ${key("enter", "select")}  ${key("n/+", "new")}  ${key("/", "filter")}  ${key("i", "invite")}  ${key("u", "default")}  ${key("d", "delete")}  ${key("?", "help")}  ${key("q", "quit")}`, 46);
     }
     out.push(M + footer + "\n");
     if (state.showHelp) {
-      out.push(`${M}  ${DIM}● default · ❯ cursor · n/+ starts guided setup · i opens /invite${RESET}${ANSI.clearLine}`);
+      out.push(M + band("● default · ❯ cursor · ✗ folder missing · d deletes an entry · esc never quits", 46));
     } else {
       out.push(ANSI.clearLine);
     }
@@ -1788,7 +1833,9 @@ async function browser(args = {}) {
       if (state.runtimeInst) {
         const runtimes = runtimeChoicesFor(state.runtimeInst, args.runtimeOverride);
         if (key.ctrl && key.name === "c") { cleanup(); process.exit(130); }
-        if (key.name === "escape") {
+        // ← is the advertised back key (enter descends, ← ascends); esc is a
+        // silent alias for the reflex — it goes back, never quits.
+        if (key.name === "escape" || key.name === "left") {
           state.runtimeInst = null;
           state.runtimeCursor = 0;
           render();
@@ -1827,16 +1874,23 @@ async function browser(args = {}) {
         return;
       }
 
-      // Modal handling takes priority
+      // Modal handling takes priority. The modal is cleared BEFORE its
+      // callback runs so a callback can chain a follow-up modal (the delete →
+      // sweep offer). Esc is a full cancel: it closes the modal and skips the
+      // chain — n/enter decline this modal but still allow the follow-up.
       if (state.modal) {
+        const m = state.modal;
         if ((chunk && /^[yY]/.test(chunk))) {
-          state.modal.onYes();
           state.modal = null;
+          m.onYes();
           render();
-        } else if (key.name === "escape" || (chunk && /^[nN]/.test(chunk)) || key.name === "return") {
-          state.modal.onNo?.();
+        } else if (key.name === "escape") {
           state.modal = null;
           render();
+        } else if ((chunk && /^[nN]/.test(chunk)) || key.name === "return") {
+          state.modal = null;
+          m.onNo?.();
+          render();
         }
         return;
       }
@@ -1908,13 +1962,20 @@ async function browser(args = {}) {
 
       // Normal mode
       if (key.ctrl && key.name === "c") { cleanup(); process.exit(130); }
-      if (key.name === "q" || key.name === "escape") {
+      // Esc never quits: at the root it only clears an active filter. Users
+      // press esc expecting either "back" or "abort" — both are safe when it
+      // can't eject them to the shell. A flash points at the real quit key.
+      if (key.name === "escape") {
         if (state.filter) {
           state.filter = "";
           clampCursor();
           render();
           return;
         }
+        flashMessage(`${BOLD}q${RESET} quits — esc never does`, "info");
+        return;
+      }
+      if (key.name === "q") {
         cleanup();
         resolve();
         return;
@@ -2000,40 +2061,49 @@ async function browser(args = {}) {
         flashMessage(`default set to ${BOLD}${pick.slug}${RESET}`, "success");
         return;
       }
-      if (chunk === "r") {
+      // d = the one delete verb (r kept as an unadvertised alias for muscle
+      // memory). Deleting confirms first; when other entries with missing
+      // folders remain, a sweep offer chains after — whether the first modal
+      // was accepted or declined, so pressing d anywhere still reaches the
+      // cleanup the notice line promises. Esc cancels without chaining.
+      if (chunk === "d" || chunk === "r") {
         const pick = visible()[state.cursor]?.e;
         if (!pick) return;
+        const offerSweep = () => {
+          const stale = registry.filter((e) => !fs.existsSync(e.path));
+          if (stale.length === 0) return;
+          state.modal = {
+            type: "sweep",
+            count: stale.length,
+            onYes: () => {
+              const bak = backupRegistry();
+              registry = registry.filter((e) => fs.existsSync(e.path));
+              writeRegistry(registry);
+              refreshStale();
+              clampCursor();
+              flashMessage(`removed ${stale.length} · ${registry.length} remain · backup: ${path.basename(bak)}`, "success");
+            },
+          };
+        };
+        const pickMissing = !fs.existsSync(pick.path);
         state.modal = {
           type: "remove",
           inst: pick,
+          missing: pickMissing,
           onYes: () => {
             const bak = backupRegistry();
             registry = registry.filter((e) => e.path !== pick.path);
             writeRegistry(registry);
             previewCache.delete(pick.path);
+            refreshStale();
             clampCursor();
             flashMessage(`removed ${BOLD}${pick.slug}${RESET} · backup: ${path.basename(bak)}`, "success");
+            offerSweep();
           },
-        };
-        render();
-        return;
-      }
-      if (chunk === "p") {
-        const stale = registry.filter((e) => !fs.existsSync(e.path));
-        if (stale.length === 0) {
-          flashMessage(`registry is clean — all ${registry.length} paths exist.`, "success");
-          return;
-        }
-        state.modal = {
-          type: "prune",
-          count: stale.length,
-          onYes: () => {
-            const bak = backupRegistry();
-            registry = registry.filter((e) => fs.existsSync(e.path));
-            writeRegistry(registry);
-            clampCursor();
-            flashMessage(`pruned ${stale.length} · ${registry.length} remain · backup: ${path.basename(bak)}`, "success");
-          },
+          // Declining a healthy row still routes to cleanup (the notice's d
+          // lands here); declining a missing row means "leave it" — don't
+          // immediately re-offer the same removal.
+          onNo: () => { if (!pickMissing) offerSweep(); },
         };
         render();
         return;

package/lib/local.js

@@ -54,6 +54,16 @@ async function listOrgs(token) {
   return data.map((o) => ({ login: o.login }));
 }
 
+// Can the token see this org at all? /user/orgs is blind to fine-grained
+// tokens and to private/SSO-gated membership, so the picker lets users type an
+// org by hand — this validates the typed login is reachable (a fine-grained
+// PAT scoped to the org returns 200 here) so a typo fails now, not at
+// repo-creation time.
+async function orgReachable(token, org) {
+  const { status } = await ghApi("GET", `/orgs/${org}`, token);
+  return status === 200;
+}
+
 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.
@@ -94,6 +104,18 @@ async function createRepo(token, owner, name, isOrg, description) {
     description: description || "Egregore shared memory",
   });
   if (status === 422) return { already_exists: true };
+  // 403 here almost always means the token can't write to THIS owner — the
+  // classic fine-grained-PAT case, where the token is scoped to one org and
+  // we're pointed at the personal account (or the wrong org). Turn GitHub's
+  // opaque "Resource not accessible by personal access token" into a next step.
+  if (status === 403) {
+    const where = isOrg ? `the ${owner} organization` : `your personal account (${owner})`;
+    throw new Error(
+      `GitHub refused repo creation in ${where} (403). ` +
+      `A fine-grained token is scoped to a single owner — re-run and choose that owner ` +
+      `as the home, or re-auth with \`gh auth login\` (unset GH_TOKEN first if it's set).`,
+    );
+  }
   if (status !== 201 && status !== 200) {
     const msg = typeof data === "object" ? data.message || JSON.stringify(data) : data;
     throw new Error(`Create repo failed (HTTP ${status}): ${msg}`);
@@ -539,14 +561,14 @@ async function maybeSetupTelegramGroup(ui, {
   ui.info(`Bot add link: ${ui.cyan(botLink)}`);
   openBrowser(botLink);
 
-  await ui.prompt("Press Enter here after the bot is in the group");
+  await ui.prompt("Press Enter here after the bot is in the group", { hint: "enter continue · ctrl-c quit" });
   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 groupLink = await ui.prompt("Telegram group join link (paste here, or Enter to skip)", { hint: "paste the link · enter skip" });
   const cleaned = groupLink.trim();
   let storedGroupLink = "";
   if (cleaned && !looksLikeUrl(cleaned)) {
@@ -677,6 +699,26 @@ async function localFounderFlow(ui, ctx = {}) {
     reposCache: null,         // {org, repos, teamRepoCount}
   };
 
+  const ENTER_ORG_LABEL = "Enter an organization name…";
+
+  const promptForOrg = async () => {
+    // Free-text org entry for the cases /user/orgs can't see (fine-grained
+    // tokens, private/SSO-gated membership). Validate reachability here so a
+    // typo or an unauthorized org fails now, with a clear message, instead of
+    // as an opaque 403 mid-creation.
+    while (true) {
+      const raw = await ui.prompt("Organization login (exact, e.g. acme-inc — blank to go back)");
+      const org = (raw || "").trim();
+      if (!org) return null;
+      const s = ui.spinner(`Checking ${org}…`);
+      if (await orgReachable(githubToken, org)) {
+        s.stop(`Found ${org}`);
+        return org;
+      }
+      s.fail(`Can't reach an org named "${org}" with this login — check the spelling, or authorize your token for it on GitHub.`);
+    }
+  };
+
   const stepHome = async () => {
     if (!st.orgs) {
       ui.section("Pick a home", "where should this Egregore live?");
@@ -684,24 +726,27 @@ async function localFounderFlow(ui, ctx = {}) {
       st.orgs = await listOrgs(githubToken);
       s.stop("Accounts loaded");
     }
-    if (st.orgs.length === 0) {
-      if (!st.githubOrg) {
-        st.githubOrg = user.login;
-        st.isOrg = false;
-        ui.info(`Using your personal account: ${ui.bold(st.githubOrg)}`);
-      }
-      return SKIP;
-    }
-    const orgChoice = await ui.choose(
-      "Where should Egregore live?",
-      [
-        { label: user.login, description: "Personal account" },
-        ...st.orgs.map((o) => ({ label: o.login, description: "Organization" })),
-      ],
-      "Don't see your org? Authorize it for your account on GitHub, then re-run.",
-      { escAction: "back" },
-    );
+    // Always offer manual org entry. /user/orgs returns nothing for
+    // fine-grained tokens and for orgs with private/SSO-gated membership, so
+    // auto-discovery alone silently strands those users on their personal
+    // account with no way to reach the org they actually want.
+    const options = [
+      { label: user.login, description: "Personal account" },
+      ...st.orgs.map((o) => ({ label: o.login, description: "Organization" })),
+      { label: ENTER_ORG_LABEL, description: "Type an org login (needed for fine-grained tokens)" },
+    ];
+    const hint = st.orgs.length === 0
+      ? "Couldn't auto-detect your orgs (normal with fine-grained tokens) — pick your account or enter an org."
+      : "Don't see your org? Enter it below, or authorize your token for it on GitHub.";
+    const orgChoice = await ui.choose("Where should Egregore live?", options, hint, { escAction: "back" });
     if (orgChoice === BACK) return BACK; // first step — driver clamps to a re-ask
+    if (orgChoice.label === ENTER_ORG_LABEL) {
+      const org = await promptForOrg();
+      if (!org) return stepHome(); // blank entry → re-show the picker (orgs cached)
+      st.githubOrg = org;
+      st.isOrg = true;
+      return true;
+    }
     st.githubOrg = orgChoice.label;
     st.isOrg = st.githubOrg !== user.login;
     return true;
@@ -725,52 +770,92 @@ async function localFounderFlow(ui, ctx = {}) {
     return true;
   };
 
-  const stepNameProject = async () => {
-    ui.section("Name it", "what's this Egregore called?");
-    if (st.isNewProject) {
-      const name = await ui.promptOrBack("name your Egregore (team or group name)", { default: st.orgName || st.githubOrg });
-      if (name === BACK) return BACK;
-      st.orgName = name;
-      const desc = await ui.promptOrBack("what are you building? (one line)", { default: st.description || undefined });
-      if (desc === BACK) return BACK;
-      st.description = desc;
-
-      // Validate the optional project repo name against the names the
-      // Egregore/memory repos WILL get (editable later, derived for now).
-      const predictedRepoName = slugifyName(st.orgName) || "egregore";
-      const predictedMemoryRepoName = `${predictedRepoName}-memory`;
-      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.",
-      ]);
-      for (;;) {
-        const projectName = await ui.promptOrBack("code project repo name (Enter to skip)", { default: st.newProjectRepo || undefined });
-        if (projectName === BACK) return BACK;
-        if (!projectName) { st.newProjectRepo = null; break; }
-        const slug = slugifyName(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;
-        }
-        st.newProjectRepo = slug;
-        break;
-      }
-    } else {
-      const name = await ui.promptOrBack("what should we call this Egregore?", { default: st.orgName || st.githubOrg });
-      if (name === BACK) return BACK;
-      st.orgName = name;
+  const stepNameManifest = async () => {
+    // One live manifest instead of scattered naming prompts: name the thing
+    // first, watch the repo plan derive from it in place, override any line.
+    // Every collision check runs against names VISIBLE on screen — the old
+    // flow rejected a code-repo name for colliding with an Egregore repo
+    // name the user had never been shown.
+    console.log("");
+    const isNew = st.isNewProject;
+    const validSlug = (v) => (slugifyName(v)
+      ? null
+      : "That doesn't produce a valid repo name. Try letters, numbers, and dashes.");
+    const fields = [
+      {
+        key: "orgName",
+        label: "Egregore",
+        note: "team or group name",
+        hint: "type your preferred Egregore name or hit enter to pick the naming below",
+        initial: st.orgName || undefined,
+        derive: () => st.githubOrg,
+      },
+      {
+        key: "repoName",
+        label: "Egregore repo",
+        note: "config + skills",
+        hint: `enter keeps this name · type to change · created in ${st.githubOrg}`,
+        tree: true,
+        initial: st.repoName || undefined,
+        derive: (v) => slugifyName(v.orgName) || "egregore",
+        normalize: (raw) => slugifyName(raw),
+        validate: (v) => validSlug(v),
+      },
+      {
+        key: "memoryRepoName",
+        label: "memory repo",
+        note: "shared memory",
+        hint: "enter keeps this name · type to change",
+        tree: true,
+        initial: st.memoryRepoName || undefined,
+        derive: (v) => `${v.repoName || "egregore"}-memory`,
+        normalize: (raw) => slugifyName(raw),
+        validate: (v, others) => validSlug(v)
+          || (v === others.repoName ? "Memory repo can't share the Egregore repo's name." : null),
+      },
+      ...(isNew ? [{
+        key: "codeRepo",
+        label: "code repo",
+        note: "your project · optional",
+        hint: "add a repo for your code project — or enter to skip",
+        tree: true,
+        optional: true,
+        initial: st.newProjectRepo || undefined,
+        normalize: (raw) => slugifyName(raw),
+        validate: (v, others) => validSlug(v)
+          || (v === others.repoName ? `"${v}" is the Egregore repo above. Pick a different name — say, ${v}-app.` : null)
+          || (v === others.memoryRepoName ? `"${v}" is the memory repo above. Pick a different name.` : null),
+      }] : []),
+    ];
+    const result = await ui.manifestForm({
+      title: "Name it",
+      subtitle: `repos land in ${st.githubOrg}`,
+      fields,
+    });
+    if (result === BACK) return BACK;
+    const v = result.values;
+    st.orgName = v.orgName;
+    st.repoName = v.repoName;
+    st.memoryRepoName = v.memoryRepoName;
+    st.newProjectRepo = isNew ? (v.codeRepo || null) : null;
+    return true;
+  };
+
+  // The one-liner is repo metadata, not a naming decision — it lives OUTSIDE
+  // the manifest so enter on the name lands directly in the naming tree
+  // (the manifest's hint promises exactly that).
+  const stepDescription = async () => {
+    if (!st.isNewProject) {
       st.description = "";
-      st.newProjectRepo = null;
+      return SKIP;
     }
+    console.log("");
+    const desc = await ui.promptOrBack("what are you building? (one line)", {
+      default: st.description || undefined,
+      hint: "one line on what you're making · enter to skip · ↑ back",
+    });
+    if (desc === BACK) return BACK;
+    st.description = desc;
     return true;
   };
 
@@ -891,41 +976,12 @@ async function localFounderFlow(ui, ctx = {}) {
     return true;
   };
 
-  const stepRepoNames = async () => {
-    // Derived names shown as editable prompts — creating repos with silently
-    // derived names was a repeated field complaint.
-    const derivedSlug = slugifyName(st.orgName) || "egregore";
-    console.log("");
-    ui.note([
-      `Two repos will be created in ${ui.bold(st.githubOrg)}: the Egregore repo`,
-      "(config + skills) and its shared-memory repo. Enter keeps the defaults.",
-    ]);
-    for (;;) {
-      const answer = await ui.promptOrBack("Egregore repo name", { default: st.repoName || derivedSlug });
-      if (answer === BACK) return BACK;
-      const candidate = slugifyName(answer);
-      if (!candidate) { ui.warn("That doesn't produce a valid repo name. Try letters, numbers, and dashes."); continue; }
-      if (st.newProjectRepo && candidate === st.newProjectRepo) { ui.warn(`"${candidate}" is already your project repo. Pick a different name.`); continue; }
-      st.repoName = candidate;
-      break;
-    }
-    for (;;) {
-      const answer = await ui.promptOrBack("memory repo name", { default: st.memoryRepoName || `${st.repoName}-memory` });
-      if (answer === BACK) return BACK;
-      const candidate = slugifyName(answer);
-      if (!candidate) { ui.warn("That doesn't produce a valid repo name. Try letters, numbers, and dashes."); continue; }
-      if (candidate === st.repoName) { ui.warn("Memory repo can't share the Egregore repo's name."); continue; }
-      if (st.newProjectRepo && candidate === st.newProjectRepo) { ui.warn(`"${candidate}" is already your project repo. Pick a different name.`); continue; }
-      st.memoryRepoName = candidate;
-      break;
-    }
-    return true;
-  };
-
   // Direction-aware driver: BACK rewinds one step; SKIP (deterministic
   // steps) passes through in whichever direction we're moving, so backing
   // over an auto-answered step doesn't bounce the user forward again.
-  const steps = [stepHome, stepWorkType, stepNameProject, stepRepos, stepRepoNames];
+  // ALL naming (Egregore + repo plan) happens in the manifest BEFORE the
+  // existing-project repo picker — name the thing first, then attach repos.
+  const steps = [stepHome, stepWorkType, stepNameManifest, stepDescription, stepRepos];
   let stepIdx = 0;
   let stepDir = 1;
   while (stepIdx < steps.length) {
@@ -1146,7 +1202,10 @@ async function localFounderFlow(ui, ctx = {}) {
 
   // 14. "What should we call you?" + write state
   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 displayName = await ui.prompt("what should we call you?", {
+    default: user.login,
+    hint: `type a display name · enter keeps ${user.login}`,
+  });
   const memberRole = await ensureInstallerMemberRole(
     { usage_type: "founder_group", member_role: ctx.memberRole },
     {},