create-egregore 0.17.4 → 0.18.0

package/lib/ui.js

@@ -1,158 +1,854 @@
 /**
  * Terminal UI — colors, spinner, prompts, banner.
  * Zero dependencies. Node 18+ built-ins only.
+ *
+ * Respects NO_COLOR (https://no-color.org) and non-TTY output.
+ * All public surfaces preserved so existing callers in cli.js /
+ * local.js / setup.js continue working.
  */
 
 const readline = require("node:readline");
 
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const GREEN = "\x1b[32m";
-const CYAN = "\x1b[36m";
-const YELLOW = "\x1b[33m";
-const RED = "\x1b[31m";
-const WHITE = "\x1b[37m";
+// ── colors ──────────────────────────────────────────────────────────
+//
+// Detect once on module load; `process.stdout.isTTY` check keeps pipes
+// and CI clean. Every escape sequence is an empty string when disabled.
 
-const BANNER = `
-${BOLD}${CYAN}  ███████╗ ██████╗ ██████╗ ███████╗ ██████╗  ██████╗ ██████╗ ███████╗
-  ██╔════╝██╔════╝ ██╔══██╗██╔════╝██╔════╝ ██╔═══██╗██╔══██╗██╔════╝
-  █████╗  ██║  ███╗██████╔╝█████╗  ██║  ███╗██║   ██║██████╔╝█████╗
-  ██╔══╝  ██║   ██║██╔══██╗██╔══╝  ██║   ██║██║   ██║██╔══██╗██╔══╝
-  ███████╗╚██████╔╝██║  ██║███████╗╚██████╔╝╚██████╔╝██║  ██║███████╗
-  ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝${RESET}
-`;
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const esc = (code) => (COLOR ? `\x1b[${code}m` : "");
 
-function banner() {
-  console.log(BANNER);
+const RESET   = esc(0);
+const BOLD    = esc(1);
+const DIM     = esc(2);
+const ITALIC  = esc(3);
+const UNDER   = esc(4);
+const INVERT  = esc(7);
+
+const BLACK   = esc(30);
+const RED     = esc(31);
+const GREEN   = esc(32);
+const YELLOW  = esc(33);
+const BLUE    = esc(34);
+const MAGENTA = esc(35);
+const CYAN    = esc(36);
+const WHITE   = esc(37);
+const GRAY    = esc(90);
+
+const BG_CYAN = esc(46);
+
+// ── layout helpers ──────────────────────────────────────────────────
+
+const termWidth = () => {
+  const w = process.stdout.columns || 80;
+  return Math.min(Math.max(w, 40), 100);
+};
+
+const pad = (s, width) => {
+  // Visible-length aware: strip escape sequences for width calc
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, "");
+  return s + " ".repeat(Math.max(0, width - visible.length));
+};
+
+// ── banners ─────────────────────────────────────────────────────────
+
+const BANNER_LINES = [
+  "  ███████╗ ██████╗ ██████╗ ███████╗ ██████╗  ██████╗ ██████╗ ███████╗",
+  "  ██╔════╝██╔════╝ ██╔══██╗██╔════╝██╔════╝ ██╔═══██╗██╔══██╗██╔════╝",
+  "  █████╗  ██║  ███╗██████╔╝█████╗  ██║  ███╗██║   ██║██████╔╝█████╗",
+  "  ██╔══╝  ██║   ██║██╔══██╗██╔══╝  ██║   ██║██║   ██║██╔══██╗██╔══╝",
+  "  ███████╗╚██████╔╝██║  ██║███████╗╚██████╔╝╚██████╔╝██║  ██║███████╗",
+  "  ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝",
+];
+
+const SIGIL_LINES = [
+  "      ◆      ",
+  "     ╱ ╲     ",
+  "    ◆───◆    ",
+  "     ╲ ╱     ",
+  "      ◆      ",
+];
+
+const COMMAND_GROUPS = [
+  { label: "core",      cmds: "/reflect /handoff /quest /todo" },
+  { label: "share",     cmds: "/save /push /branch /pr" },
+  { label: "knowledge", cmds: "/add /note /meeting /ingest" },
+  { label: "identity",  cmds: "/me /invite /announce" },
+];
+
+function banner(subtitle) {
+  process.stdout.write("\n");
+  for (const line of BANNER_LINES) {
+    process.stdout.write(`${BOLD}${CYAN}${line}${RESET}\n`);
+  }
+  if (subtitle) {
+    process.stdout.write(`\n  ${DIM}${subtitle}${RESET}\n`);
+  }
+  process.stdout.write("\n");
 }
 
+function bannerCompact(label) {
+  // One-line brand tag for subsequent screens after the big banner.
+  process.stdout.write(`\n  ${BOLD}${CYAN}egregore${RESET}${DIM} · ${label || "setup"}${RESET}\n\n`);
+}
+
+// ── structural primitives ───────────────────────────────────────────
+
+function section(title, subtitle) {
+  // A divider line + bold title. Use between major phases of a flow.
+  const w = termWidth() - 4;
+  process.stdout.write(`\n  ${DIM}${"─".repeat(w)}${RESET}\n`);
+  process.stdout.write(`  ${BOLD}${title}${RESET}`);
+  if (subtitle) {
+    process.stdout.write(`  ${DIM}${subtitle}${RESET}`);
+  }
+  process.stdout.write("\n\n");
+}
+
+function note(lines) {
+  // A soft-highlighted multi-line note. Use for framing text, insights,
+  // explanations that deserve more weight than a plain info() but don't
+  // need a full box.
+  const arr = Array.isArray(lines) ? lines : [lines];
+  process.stdout.write("\n");
+  for (const line of arr) {
+    if (line === "") {
+      process.stdout.write(`  ${CYAN}│${RESET}\n`);
+    } else {
+      process.stdout.write(`  ${CYAN}│${RESET}  ${line}\n`);
+    }
+  }
+  process.stdout.write("\n");
+}
+
+function card(title, body) {
+  // A bordered card for standout content (e.g. an invite command to share).
+  const bodyLines = Array.isArray(body) ? body : [body];
+  const contentWidth = Math.max(
+    title.length,
+    ...bodyLines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").length),
+  );
+  const boxW = contentWidth + 4;
+
+  process.stdout.write("\n");
+  process.stdout.write(`  ${DIM}┌─ ${title} ${"─".repeat(Math.max(0, boxW - title.length - 4))}┐${RESET}\n`);
+  process.stdout.write(`  ${DIM}│${" ".repeat(boxW)}│${RESET}\n`);
+  for (const line of bodyLines) {
+    const visLen = line.replace(/\x1b\[[0-9;]*m/g, "").length;
+    const padded = line + " ".repeat(Math.max(0, boxW - visLen - 2));
+    process.stdout.write(`  ${DIM}│${RESET}  ${BOLD}${padded}${RESET}${DIM}│${RESET}\n`);
+  }
+  process.stdout.write(`  ${DIM}│${" ".repeat(boxW)}│${RESET}\n`);
+  process.stdout.write(`  ${DIM}└${"─".repeat(boxW)}┘${RESET}\n\n`);
+}
+
+// ── messages ────────────────────────────────────────────────────────
+
 function info(msg) {
-  console.log(`  ${msg}`);
+  process.stdout.write(`  ${msg}\n`);
 }
 
 function success(msg) {
-  console.log(`  ${GREEN}✓${RESET} ${msg}`);
+  process.stdout.write(`  ${GREEN}✓${RESET} ${msg}\n`);
 }
 
 function warn(msg) {
-  console.log(`  ${YELLOW}!${RESET} ${msg}`);
+  process.stdout.write(`  ${YELLOW}!${RESET} ${msg}\n`);
 }
 
 function error(msg) {
-  console.error(`  ${RED}✗${RESET} ${msg}`);
+  process.stderr.write(`  ${RED}✗${RESET} ${msg}\n`);
 }
 
 function step(n, total, msg) {
-  console.log(`\n  ${DIM}[${n}/${total}]${RESET} ${msg}`);
+  process.stdout.write(`\n  ${DIM}[${n}/${total}]${RESET} ${msg}\n`);
 }
 
-function dim(msg) {
-  return `${DIM}${msg}${RESET}`;
-}
+// ── inline formatters ──────────────────────────────────────────────
 
-function bold(msg) {
-  return `${BOLD}${msg}${RESET}`;
-}
+const dim    = (m) => `${DIM}${m}${RESET}`;
+const bold   = (m) => `${BOLD}${m}${RESET}`;
+const cyan   = (m) => `${CYAN}${m}${RESET}`;
+const green  = (m) => `${GREEN}${m}${RESET}`;
+const yellow = (m) => `${YELLOW}${m}${RESET}`;
+const red    = (m) => `${RED}${m}${RESET}`;
 
-function cyan(msg) {
-  return `${CYAN}${msg}${RESET}`;
-}
+// ── spinner ─────────────────────────────────────────────────────────
 
-// Simple spinner
 function spinner(msg) {
   const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
   let i = 0;
-  const interval = setInterval(() => {
-    process.stdout.write(`\r  ${CYAN}${frames[i++ % frames.length]}${RESET} ${msg}`);
-  }, 80);
+  const tty = process.stdout.isTTY;
+  let interval = null;
+  if (tty) {
+    interval = setInterval(() => {
+      process.stdout.write(`\r  ${CYAN}${frames[i++ % frames.length]}${RESET} ${msg}`);
+    }, 80);
+  } else {
+    // Non-TTY: just print once, don't animate
+    process.stdout.write(`  … ${msg}\n`);
+  }
   return {
     stop(result) {
-      clearInterval(interval);
-      process.stdout.write(`\r\x1b[2K  ${GREEN}✓${RESET} ${result || msg}\n`);
+      if (interval) clearInterval(interval);
+      if (tty) process.stdout.write(`\r\x1b[2K`);
+      process.stdout.write(`  ${GREEN}✓${RESET} ${result || msg}\n`);
     },
     fail(result) {
-      clearInterval(interval);
-      process.stdout.write(`\r\x1b[2K  ${RED}✗${RESET} ${result || msg}\n`);
+      if (interval) clearInterval(interval);
+      if (tty) process.stdout.write(`\r\x1b[2K`);
+      process.stdout.write(`  ${RED}✗${RESET} ${result || msg}\n`);
+    },
+    // Stop animating and erase the line without printing a result symbol —
+    // for when the caller prints its own success/failure line next.
+    clear() {
+      if (interval) clearInterval(interval);
+      if (tty) process.stdout.write(`\r\x1b[2K`);
     },
   };
 }
 
-// Prompt for input
-function prompt(question) {
+// ── prompts ─────────────────────────────────────────────────────────
+
+function prompt(question, { default: defaultValue } = {}) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout,
     });
-    rl.question(`  ${question} `, (answer) => {
+    const label = defaultValue
+      ? `${CYAN}?${RESET} ${question} ${DIM}[${defaultValue}]${RESET} `
+      : `${CYAN}?${RESET} ${question} `;
+    rl.question(`  ${label}`, (answer) => {
       rl.close();
-      resolve(answer.trim());
+      const trimmed = answer.trim();
+      resolve(trimmed || (defaultValue ?? ""));
     });
   });
 }
 
-// Prompt with numbered choices
+async function confirm(question, defaultYes = false) {
+  const hint = defaultYes ? `${DIM}[Y/n]${RESET}` : `${DIM}[y/N]${RESET}`;
+  const answer = await prompt(`${question} ${hint}`);
+  if (!answer) return defaultYes;
+  return /^y(es)?$/i.test(answer);
+}
+
+// ── interactive pickers ─────────────────────────────────────────────
+//
+// Arrow-key navigation + type-to-filter + Enter to select + Esc to cancel.
+// Uses Node readline raw mode; no external dependencies.
+//
+// Falls back to numbered input when stdin/stdout aren't TTYs (CI, pipes,
+// non-interactive shells).
+
+function canInteract() {
+  return process.stdin.isTTY && process.stdout.isTTY && !process.env.EGREGORE_NO_INTERACTIVE;
+}
+
+// Visible length (strips ANSI escape sequences) for padding math.
+const visibleLen = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
+
+function visualRows(line, width = process.stdout.columns || 80) {
+  return Math.max(1, Math.ceil(visibleLen(line) / Math.max(1, width)));
+}
+
+// Render a picker frame and return { lines: number } so the next frame can
+// rewind and clear. Shared by choose + multiSelect.
+function renderPicker({ question, filterText, lines, help }) {
+  const out = [];
+  const filterLabel = filterText
+    ? `  ${DIM}filter:${RESET} ${filterText}${CYAN}▌${RESET}`
+    : "";
+  out.push(`  ${CYAN}◆${RESET} ${BOLD}${question}${RESET}${filterLabel ? "   " + filterLabel : ""}`);
+  out.push("");
+  for (const line of lines) out.push(line);
+  if (help) {
+    out.push("");
+    out.push(`  ${DIM}${help}${RESET}`);
+  }
+  const text = out.join("\n") + "\n";
+  process.stdout.write(text);
+  const width = process.stdout.columns || 80;
+  return out.reduce((sum, line) => sum + visualRows(line, width), 0);
+}
+
+function clearLines(n) {
+  if (n <= 0) return;
+  // Move up n lines and clear from cursor to end of screen.
+  process.stdout.write(`\x1b[${n}A\x1b[0J`);
+}
+
+function filterOptions(options, filterText, getText) {
+  if (!filterText) return options.map((o, i) => ({ opt: o, origIdx: i }));
+  const q = filterText.toLowerCase();
+  const result = [];
+  for (let i = 0; i < options.length; i++) {
+    const text = getText(options[i]).toLowerCase();
+    if (text.includes(q)) result.push({ opt: options[i], origIdx: i });
+  }
+  return result;
+}
+
+// ── choose: interactive single-select picker ────────────────────────
+//
+// options: [{ label, description }]
+// returns: the picked option (same object reference as in options[])
+// keys:
+//   ↑ ↓       navigate
+//   enter     select
+//   type      filter (case-insensitive substring match on label + desc)
+//   backspace pop filter
+//   esc       cancel (returns the first option, or throws if opts.abortOnEsc)
+//   ctrl-c    abort process
+
 async function choose(question, options, hint) {
-  console.log(`\n  ${question}\n`);
+  if (!canInteract()) return legacyChoose(question, options, hint);
+  return interactiveChoose(question, options, hint);
+}
+
+async function interactiveChoose(question, options, hint) {
+  return new Promise((resolve) => {
+    let cursor = 0;
+    let filterText = "";
+    let visible = filterOptions(options, filterText, (o) => `${o.label} ${o.description || ""}`);
+    let lastLineCount = 0;
+
+    const labelWidth = Math.min(
+      40,
+      Math.max(...options.map((o) => o.label.length)),
+    );
+
+    const render = (first = false) => {
+      const lines = visible.map((entry, i) => {
+        const { opt } = entry;
+        const selected = i === cursor;
+        const marker = selected ? `${CYAN}❯${RESET}` : " ";
+        const labelPart = selected ? `${BOLD}${CYAN}${pad(opt.label, labelWidth)}${RESET}` : pad(opt.label, labelWidth);
+        const desc = opt.description ? `  ${DIM}${opt.description}${RESET}` : "";
+        return `    ${marker}  ${labelPart}${desc}`;
+      });
+      if (visible.length === 0) {
+        lines.push(`    ${DIM}(no matches)${RESET}`);
+      }
+      if (!first) clearLines(lastLineCount);
+      lastLineCount = renderPicker({
+        question,
+        filterText,
+        lines,
+        help: hint || `${DIM}↑↓${RESET} navigate · ${DIM}enter${RESET} select · type to filter · ${DIM}esc${RESET} cancel`,
+      });
+    };
+
+    const cleanup = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("keypress", onKey);
+    };
+
+    const finish = (value) => {
+      cleanup();
+      clearLines(lastLineCount);
+      process.stdout.write(`  ${CYAN}◆${RESET} ${BOLD}${question}${RESET}  ${DIM}→${RESET} ${BOLD}${value.label}${RESET}\n`);
+      resolve(value);
+    };
+
+    const onKey = (_str, key) => {
+      if (!key) return;
+      if ((key.ctrl && key.name === "c") || key.name === "escape") {
+        cleanup();
+        process.stdout.write(`\n  ${DIM}(cancelled)${RESET}\n`);
+        process.exit(130);
+      }
+      if (key.name === "return") {
+        if (visible.length > 0) finish(visible[cursor].opt);
+        return;
+      }
+      if (key.name === "up" || (key.ctrl && key.name === "p")) {
+        cursor = (cursor - 1 + visible.length) % Math.max(1, visible.length);
+        render();
+        return;
+      }
+      if (key.name === "down" || (key.ctrl && key.name === "n")) {
+        cursor = (cursor + 1) % Math.max(1, visible.length);
+        render();
+        return;
+      }
+      if (key.name === "backspace") {
+        filterText = filterText.slice(0, -1);
+        visible = filterOptions(options, filterText, (o) => `${o.label} ${o.description || ""}`);
+        cursor = 0;
+        render();
+        return;
+      }
+      // Printable character → append to filter
+      if (_str && _str.length === 1 && !key.ctrl && !key.meta && _str.charCodeAt(0) >= 32) {
+        filterText += _str;
+        visible = filterOptions(options, filterText, (o) => `${o.label} ${o.description || ""}`);
+        cursor = 0;
+        render();
+      }
+    };
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("keypress", onKey);
+    render(true);
+  });
+}
+
+async function legacyChoose(question, options, hint) {
+  process.stdout.write(`\n  ${CYAN}◆${RESET} ${BOLD}${question}${RESET}\n\n`);
+  const labelWidth = Math.min(40, Math.max(...options.map((o) => o.label.length)));
   for (let i = 0; i < options.length; i++) {
     const { label, description } = options[i];
-    console.log(`  ${BOLD}${i + 1}.${RESET} ${label}${description ? ` ${DIM}— ${description}${RESET}` : ""}`);
+    const num = String(i + 1).padStart(2, " ");
+    const paddedLabel = pad(label, labelWidth);
+    const desc = description ? `  ${DIM}— ${description}${RESET}` : "";
+    process.stdout.write(`    ${DIM}${num})${RESET} ${BOLD}${paddedLabel}${RESET}${desc}\n`);
   }
-  if (hint) console.log(`\n  ${DIM}${hint}${RESET}`);
-  console.log();
-
+  if (hint) process.stdout.write(`\n  ${DIM}${hint}${RESET}\n`);
   while (true) {
-    const answer = await prompt(`Pick [1-${options.length}]:`);
+    const answer = await prompt(`pick ${DIM}[1-${options.length}]${RESET}:`);
+    if (!answer) { warn(`Enter a number between 1 and ${options.length}.`); continue; }
     const n = parseInt(answer, 10);
-    if (n >= 1 && n <= options.length) {
-      return options[n - 1];
-    }
-    warn(`Enter a number between 1 and ${options.length}`);
+    if (n >= 1 && n <= options.length) return options[n - 1];
+    const labelMatch = options.find((o) => o.label.toLowerCase() === answer.toLowerCase());
+    if (labelMatch) return labelMatch;
+    warn(`Not a valid option. Enter 1-${options.length} or a label.`);
   }
 }
 
-// Prompt with multi-select (comma-separated numbers, or Enter to skip)
+// ── multiSelect: interactive multi-select picker ────────────────────
+//
+// options: [{ name, language?, description? }]
+// returns: array of picked names
+// keys:
+//   ↑ ↓       navigate
+//   space     toggle current
+//   a         toggle all (respecting filter)
+//   enter     confirm
+//   type      filter
+//   esc       confirm with current selection
+
 async function multiSelect(question, options) {
   if (options.length === 0) return [];
-  console.log(`\n  ${question}\n`);
+  if (!canInteract()) return legacyMultiSelect(question, options);
+  return interactiveMultiSelect(question, options);
+}
+
+async function interactiveMultiSelect(question, options) {
+  return new Promise((resolve) => {
+    let cursor = 0;
+    let filterText = "";
+    const picked = new Set();
+    let visible = filterOptions(options, filterText, (o) => `${o.name} ${o.description || ""} ${o.language || ""}`);
+    let lastLineCount = 0;
+
+    const nameWidth = Math.min(36, Math.max(...options.map((o) => (o.name || "").length)));
+
+    const render = (first = false) => {
+      const lines = visible.map((entry, i) => {
+        const { opt } = entry;
+        const isCursor = i === cursor;
+        const isPicked = picked.has(opt.name);
+        const cursorMark = isCursor ? `${CYAN}❯${RESET}` : " ";
+        const checkbox = isPicked ? `${GREEN}[✓]${RESET}` : `${DIM}[ ]${RESET}`;
+        const name = isCursor ? `${BOLD}${CYAN}${pad(opt.name, nameWidth)}${RESET}` : pad(opt.name, nameWidth);
+        const lang = opt.language ? `  ${DIM}(${opt.language})${RESET}` : "";
+        const desc = opt.description ? `  ${DIM}${opt.description}${RESET}` : "";
+        return `    ${cursorMark}  ${checkbox}  ${name}${lang}${desc}`;
+      });
+      if (visible.length === 0) {
+        lines.push(`    ${DIM}(no matches)${RESET}`);
+      }
+      lines.push("");
+      lines.push(`    ${DIM}${picked.size} selected${RESET}`);
+      if (!first) clearLines(lastLineCount);
+      lastLineCount = renderPicker({
+        question,
+        filterText,
+        lines,
+        help: `${DIM}↑↓${RESET} nav · ${DIM}space${RESET} toggle · ${DIM}a${RESET} all · ${DIM}enter${RESET} confirm · type to filter`,
+      });
+    };
+
+    const cleanup = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("keypress", onKey);
+    };
+
+    const finish = () => {
+      cleanup();
+      clearLines(lastLineCount);
+      const summary = picked.size === 0 ? `${DIM}none${RESET}` : `${BOLD}${picked.size}${RESET} ${DIM}selected${RESET}`;
+      process.stdout.write(`  ${CYAN}◆${RESET} ${BOLD}${question}${RESET}  ${DIM}→${RESET} ${summary}\n`);
+      resolve([...picked]);
+    };
+
+    const toggleCurrent = () => {
+      if (visible.length === 0) return;
+      const name = visible[cursor].opt.name;
+      if (picked.has(name)) picked.delete(name);
+      else picked.add(name);
+    };
+
+    const toggleAll = () => {
+      // If every visible option is already picked, unselect all visible; else pick all visible.
+      const allPicked = visible.every((v) => picked.has(v.opt.name));
+      for (const v of visible) {
+        if (allPicked) picked.delete(v.opt.name);
+        else picked.add(v.opt.name);
+      }
+    };
+
+    const onKey = (_str, key) => {
+      if (!key) return;
+      if ((key.ctrl && key.name === "c") || key.name === "escape") {
+        cleanup();
+        process.stdout.write(`\n  ${DIM}(cancelled)${RESET}\n`);
+        process.exit(130);
+      }
+      if (key.name === "return") return finish();
+      if (key.name === "up" || (key.ctrl && key.name === "p")) {
+        cursor = (cursor - 1 + visible.length) % Math.max(1, visible.length);
+        render();
+        return;
+      }
+      if (key.name === "down" || (key.ctrl && key.name === "n")) {
+        cursor = (cursor + 1) % Math.max(1, visible.length);
+        render();
+        return;
+      }
+      if (key.name === "space") {
+        toggleCurrent();
+        render();
+        return;
+      }
+      if (_str === "a" && !filterText) {
+        toggleAll();
+        render();
+        return;
+      }
+      if (key.name === "backspace") {
+        filterText = filterText.slice(0, -1);
+        visible = filterOptions(options, filterText, (o) => `${o.name} ${o.description || ""} ${o.language || ""}`);
+        cursor = 0;
+        render();
+        return;
+      }
+      if (_str && _str.length === 1 && !key.ctrl && !key.meta && _str.charCodeAt(0) >= 32) {
+        filterText += _str;
+        visible = filterOptions(options, filterText, (o) => `${o.name} ${o.description || ""} ${o.language || ""}`);
+        cursor = 0;
+        render();
+      }
+    };
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("keypress", onKey);
+    render(true);
+  });
+}
+
+async function legacyMultiSelect(question, options) {
+  process.stdout.write(`\n  ${CYAN}◆${RESET} ${BOLD}${question}${RESET}\n\n`);
+  const nameWidth = Math.min(36, Math.max(...options.map((o) => (o.name || "").length)));
   for (let i = 0; i < options.length; i++) {
     const { name, language, description } = options[i];
-    const lang = language ? `${DIM}(${language})${RESET} ` : "";
-    const desc = description ? `${DIM}— ${description}${RESET}` : "";
-    console.log(`  ${BOLD}${i + 1}.${RESET} ${name} ${lang}${desc}`);
+    const num = String(i + 1).padStart(2, " ");
+    const paddedName = pad(name || "", nameWidth);
+    const lang = language ? `  ${DIM}(${language})${RESET}` : "";
+    const desc = description ? `  ${DIM}— ${description}${RESET}` : "";
+    process.stdout.write(`    ${DIM}${num})${RESET} ${paddedName}${lang}${desc}\n`);
+  }
+  process.stdout.write(`\n  ${DIM}numbers (e.g. 1,3-5), 'all', or Enter to skip${RESET}\n`);
+  const answer = await prompt("select:");
+  if (!answer || /^none$/i.test(answer)) return [];
+  if (/^all$/i.test(answer)) return options.map((o) => o.name);
+  const picked = new Set();
+  for (const part of answer.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const range = part.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (range) {
+      const [, a, b] = range;
+      const lo = Math.min(+a, +b);
+      const hi = Math.max(+a, +b);
+      for (let n = lo; n <= hi; n++) {
+        if (n >= 1 && n <= options.length) picked.add(options[n - 1].name);
+      }
+    } else {
+      const n = parseInt(part, 10);
+      if (n >= 1 && n <= options.length) picked.add(options[n - 1].name);
+    }
   }
-  console.log(`\n  ${DIM}Enter numbers (e.g. 1,3,5), 'all', or press Enter to skip${RESET}`);
+  return [...picked];
+}
+
+// ── commandBox ──────────────────────────────────────────────────────
+//
+// Preserved for back-compat; card() is the newer more-flexible version.
 
-  const answer = await prompt("Repos:");
-  if (!answer) return [];
-  if (answer.toLowerCase() === "all") return options.map((o) => o.name);
+function commandBox(label, cmd) {
+  card(label, cmd);
+}
 
-  const selected = [];
-  for (const part of answer.split(",")) {
-    const n = parseInt(part.trim(), 10);
-    if (n >= 1 && n <= options.length) {
-      selected.push(options[n - 1].name);
+// ── bookend screens (alt-screen) ───────────────────────────────────
+//
+// Full-screen welcome + summary moments that bracket the linear install
+// flow. Enter alt-screen, render, wait for ENTER, exit alt-screen. This
+// preserves both the user's prior shell scrollback AND the install
+// transcript — the full-screen moment is the only thing that disappears.
+//
+// Fallback: callers should check canShowScreens() and fall back to inline
+// renderers for non-TTY / CI / --no-screens.
+
+const ALT_SCREEN_IN  = "\x1b[?1049h";
+const ALT_SCREEN_OUT = "\x1b[?1049l";
+const CURSOR_HIDE    = "\x1b[?25l";
+const CURSOR_SHOW    = "\x1b[?25h";
+const CLEAR_HOME     = "\x1b[2J\x1b[H";
+
+function canShowScreens() {
+  return !!(process.stdin.isTTY && process.stdout.isTTY && !process.env.EGREGORE_NO_SCREENS);
+}
+
+function termSize() {
+  return {
+    w: process.stdout.columns || 80,
+    h: process.stdout.rows || 24,
+  };
+}
+
+// Visible length (strips ANSI) for centering math.
+function _visLen(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+// Center a string horizontally by prepending spaces.
+function _center(line, w) {
+  const pad = Math.max(0, Math.floor((w - _visLen(line)) / 2));
+  return " ".repeat(pad) + line;
+}
+
+// Pad vertical space to push content toward center-ish.
+function _vpad(n) {
+  return Array.from({ length: Math.max(0, n) }, () => "").join("\n");
+}
+
+async function _waitForEnter() {
+  return new Promise((resolve) => {
+    let done = false;
+    const onKey = (chunk, key) => {
+      if (done) return;
+      if (key && key.ctrl && key.name === "c") {
+        // Clean exit on ctrl-c — teardown alt-screen first
+        process.stdout.write(CURSOR_SHOW + ALT_SCREEN_OUT);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeListener("keypress", onKey);
+        process.exit(130);
+      }
+      if (key && (key.name === "return" || key.name === "escape" || key.name === "space")) {
+        done = true;
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeListener("keypress", onKey);
+        resolve(key.name);
+      }
+    };
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("keypress", onKey);
+  });
+}
+
+function _readPkgVersion() {
+  try {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const raw = fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf-8");
+    return JSON.parse(raw).version;
+  } catch {
+    return "?";
+  }
+}
+
+function _renderWelcomeBody({ w, h, version }) {
+  const panelInner = Math.min(76, Math.max(62, w - 6));
+  const panelOuter = panelInner + 2;
+  const showBanner = h >= 28 && w >= 74;
+
+  const lines = [];
+
+  if (showBanner) {
+    for (const l of BANNER_LINES) {
+      lines.push(`${BOLD}${CYAN}${l}${RESET}`);
     }
+  } else {
+    lines.push(`${BOLD}${CYAN}EGREGORE${RESET}`);
   }
-  return selected;
+  lines.push("");
+
+  const leftWidth = 14;
+  const gutter = 2;
+  const rightWidth = panelInner - leftWidth - gutter - 2;
+
+  const leftLines = [
+    "",
+    ...SIGIL_LINES.map((l) => `${CYAN}${l}${RESET}`),
+    "",
+    "",
+    `${BOLD}create-egregore${RESET}`,
+    `${DIM}v${version}${RESET}`,
+  ];
+
+  const rightLines = [];
+  rightLines.push(`${BOLD}What you're installing${RESET}`);
+  rightLines.push("");
+  for (const g of COMMAND_GROUPS) {
+    rightLines.push(`${DIM}${pad(g.label, 10)}${RESET}  ${g.cmds}`);
+  }
+  rightLines.push("");
+  rightLines.push(`${BOLD}Mode${RESET}`);
+  rightLines.push(`${DIM}local-first · memory lives in ./memory/${RESET}`);
+  rightLines.push(`${DIM}files are yours · git is the source of truth${RESET}`);
+  rightLines.push("");
+  rightLines.push(`${BOLD}Next${RESET}`);
+  rightLines.push(`${DIM}guided setup → choose an assistant${RESET}`);
+
+  const panelHeight = Math.max(leftLines.length, rightLines.length);
+  while (leftLines.length < panelHeight) leftLines.push("");
+  while (rightLines.length < panelHeight) rightLines.push("");
+
+  const label = " create-egregore ";
+  const dashesLeft = 2;
+  const dashesRight = Math.max(0, panelInner - label.length - dashesLeft);
+  lines.push(`${DIM}┌${"─".repeat(dashesLeft)}${RESET}${DIM}${label}${RESET}${DIM}${"─".repeat(dashesRight)}┐${RESET}`);
+  lines.push(`${DIM}│${RESET}${" ".repeat(panelInner)}${DIM}│${RESET}`);
+
+  for (let i = 0; i < panelHeight; i++) {
+    const left = leftLines[i];
+    const leftPad = " ".repeat(Math.max(0, leftWidth - visibleLen(left)));
+    const right = rightLines[i];
+    const rightPad = " ".repeat(Math.max(0, rightWidth - visibleLen(right)));
+    const inner = ` ${left}${leftPad}${" ".repeat(gutter)}${right}${rightPad} `;
+    const innerPad = " ".repeat(Math.max(0, panelInner - visibleLen(inner)));
+    lines.push(`${DIM}│${RESET}${inner}${innerPad}${DIM}│${RESET}`);
+  }
+
+  lines.push(`${DIM}│${RESET}${" ".repeat(panelInner)}${DIM}│${RESET}`);
+  lines.push(`${DIM}└${"─".repeat(panelInner)}┘${RESET}`);
+
+  lines.push("");
+  lines.push(`${DIM}a shared memory layer for teams using Claude Code or Codex${RESET}`);
+  lines.push("");
+  lines.push(`${DIM}press ${RESET}${BOLD}↵${RESET}${DIM} to begin · ctrl-c to exit${RESET}`);
+
+  const margin = Math.max(0, Math.floor((w - panelOuter) / 2));
+  const rendered = lines.map((l) => " ".repeat(margin) + l);
+  const topPad = Math.max(0, Math.floor((h - lines.length - 1) / 4));
+  const bottomPad = Math.max(0, h - lines.length - topPad - 1);
+
+  return { body: rendered.join("\n"), topPad, bottomPad };
 }
 
-function commandBox(label, cmd) {
-  const inner = `   ${cmd}   `;
-  const width = Math.max(inner.length, label.length + 5);
-  const pad = (s) => s + " ".repeat(Math.max(0, width - s.length));
-  const top = `┌─ ${label} ${"─".repeat(Math.max(0, width - label.length - 4))}┐`;
-  const blank = `│${" ".repeat(width)}│`;
-  const bot = `└${"─".repeat(width)}┘`;
-  console.log(`\n  ${DIM}${top}${RESET}`);
-  console.log(`  ${DIM}${blank}${RESET}`);
-  console.log(`  ${DIM}│${RESET}${BOLD}${pad(inner)}${RESET}${DIM}│${RESET}`);
-  console.log(`  ${DIM}${blank}${RESET}`);
-  console.log(`  ${DIM}${bot}${RESET}\n`);
+async function welcomeScreen(_opts = {}) {
+  const { w, h } = termSize();
+  const version = _readPkgVersion();
+  const { body, topPad, bottomPad } = _renderWelcomeBody({ w, h, version });
+
+  process.stdout.write(ALT_SCREEN_IN + CURSOR_HIDE + CLEAR_HOME);
+  process.stdout.write(_vpad(topPad));
+  process.stdout.write("\n");
+  process.stdout.write(body);
+  process.stdout.write(_vpad(bottomPad));
+
+  const result = await _waitForEnter();
+  process.stdout.write(CURSOR_SHOW + ALT_SCREEN_OUT);
+  if (result === "escape") process.exit(0);
+}
+
+// Summary / ready screen — bookend at the end of the install. Shows the
+// workspace that was created, the framing Insight (so the first Claude
+// session can skip re-rendering it), and a "press enter to start your
+// first session" prompt. After enter, alt-screen leaves and the caller
+// execs into `claude start`.
+async function summaryScreen({ orgName, workspaces = [], next = "start your first session", setup = null } = {}) {
+  const { w, h } = termSize();
+  const lines = [];
+
+  lines.push(`${BOLD}${GREEN}✓ You're done${RESET}`);
+  lines.push("");
+  lines.push(`${DIM}Egregore is ready for${RESET} ${BOLD}${orgName}${RESET}`);
+  lines.push("");
+
+  if (setup) {
+    const rows = [
+      ["workspace", setup.workspace || "created"],
+      ["invite", setup.invite || "skipped"],
+      ["Telegram", setup.telegram || "skipped"],
+      ["assistant", setup.assistant || ""],
+      ["next", setup.command || "egregore"],
+    ].filter(([, value]) => value);
+    lines.push(`${DIM}setup${RESET}`);
+    for (const [label, value] of rows) {
+      lines.push(`  ${GREEN}●${RESET}  ${DIM}${pad(label, 10)}${RESET} ${value}`);
+    }
+    lines.push("");
+  }
+
+  if (workspaces.length) {
+    lines.push(`${DIM}workspace${RESET}`);
+    for (const ws of workspaces) {
+      const label = ws.label || "";
+      const desc = ws.description || "";
+      lines.push(`  ${GREEN}●${RESET}  ${CYAN}${label}${RESET}   ${DIM}${desc}${RESET}`);
+    }
+    lines.push("");
+  }
+
+  // Framing Insight — this is the copy that /onboarding used to render.
+  // Showing it here means the first Claude session can skip it entirely.
+  lines.push("");
+  lines.push(`${DIM}${"─".repeat(Math.min(48, w - 20))}${RESET}`);
+  lines.push("");
+  lines.push("Every session leaves traces — decisions, patterns, context.");
+  lines.push(`${DIM}Egregore makes those traces persistent and shared.${RESET}`);
+  lines.push("");
+  lines.push("You do your work. When you're done, you hand off what you");
+  lines.push(`learned. The next session — yours or someone else's —`);
+  lines.push(`${DIM}starts smarter.${RESET}`);
+  lines.push("");
+  lines.push(`${DIM}${"─".repeat(Math.min(48, w - 20))}${RESET}`);
+  lines.push("");
+  lines.push("");
+  lines.push(`${DIM}press ${RESET}${BOLD}↵${RESET}${DIM} to ${next} · esc to skip launch${RESET}`);
+
+  const rendered = lines.map((l) => _center(l, w));
+  const topPad = Math.max(1, Math.floor((h - lines.length - 2) / 4));
+  const bottomPad = Math.max(0, h - lines.length - topPad - 1);
+
+  process.stdout.write(ALT_SCREEN_IN + CURSOR_HIDE + CLEAR_HOME);
+  process.stdout.write(_vpad(topPad));
+  process.stdout.write("\n");
+  process.stdout.write(rendered.join("\n"));
+  process.stdout.write(_vpad(bottomPad));
+
+  const result = await _waitForEnter();
+  process.stdout.write(CURSOR_SHOW + ALT_SCREEN_OUT);
+  return result; // "return" (launch) | "escape" (skip launch) | "space"
 }
 
 module.exports = {
-  banner, info, success, warn, error, step, dim, bold, cyan,
-  spinner, prompt, choose, multiSelect, commandBox,
+  banner, bannerCompact, section, note, card,
+  info, success, warn, error, step,
+  dim, bold, cyan, green, yellow, red,
+  spinner, prompt, choose, multiSelect, confirm,
+  commandBox,
+  canShowScreens, welcomeScreen, summaryScreen,
+  _renderWelcomeBody, _readPkgVersion,
 };