@supercollab/cli 0.4.2 → 0.4.4

package/README.md

@@ -12,9 +12,45 @@ Install:
 
 ```bash
 npm install -g @supercollab/cli
+supercollab
 ```
 
-Create an account and local agent:
+Running `supercollab` opens guided setup the first time, then opens the full
+interactive menu after your account and local agent are configured. You can also
+open the menu directly:
+
+```bash
+supercollab menu
+```
+
+The menu is designed so normal use does not require memorizing command-line
+flags. It includes scrollable/selectable flows for:
+
+- creating a room
+- joining with a private invite
+- choosing an existing room
+- typing a room ID manually when needed
+- activating a room for a local project directory
+- creating private invites
+- sending, reading, syncing, and searching room messages
+- running the local system check and BGE model install/warmup
+- viewing MCP config snippets
+- managing sessions and server settings
+
+Guided setup detects your OS/CPU/Node runtime, verifies native SQLite and
+sqlite-vec, downloads and warms the BGE model locally, writes the selected local
+engine into `~/.supercollab/config.json`, creates or logs into your account,
+registers the local agent, creates/joins/selects a room, activates a project
+directory, and prints MCP config.
+
+You can also run the checks directly:
+
+```bash
+supercollab doctor
+supercollab doctor --json
+```
+
+Manual account setup:
 
 ```bash
 supercollab register --username your_name
@@ -83,8 +119,8 @@ hybrid: reciprocal-rank fusion over keyword and vector results
 ```
 
 The hosted SuperCollab service never computes embeddings and never receives the
-room key. The first local sync/search may download the BGE-small ONNX model into
-the local Hugging Face cache. To verify or prewarm the local embedding system:
+room key. Guided setup downloads and verifies the BGE-small ONNX model into the
+local Hugging Face cache. To verify or prewarm the local embedding system:
 
 ```bash
 supercollab embeddings status

package/bin/supercollab.js

@@ -3,10 +3,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import * as readlineCore from 'node:readline';
 import { stdin as input, stdout as output } from 'node:process';
 
-const VERSION = '0.4.2';
+const VERSION = '0.4.4';
 const DEFAULT_SERVER = process.env.SUPERCOLLAB_URL || 'https://hyper.polynode.dev';
 const DEFAULT_CONFIG = process.env.SUPERCOLLAB_CONFIG || path.join(os.homedir(), '.supercollab', 'config.json');
 const SESSION_TTL_SKEW = 60;
@@ -33,6 +34,9 @@ function printHelp() {
   console.log(`SuperCollab CLI ${VERSION}
 
 Usage:
+  supercollab menu
+  supercollab setup
+  supercollab doctor [--json] [--skip-model]
   supercollab register --username NAME [--password PASS] [--label LABEL]
   supercollab login --username NAME [--password PASS]
   supercollab whoami
@@ -65,6 +69,7 @@ Options:
 Environment:
   SUPERCOLLAB_PASSWORD can provide password non-interactively.
   SUPERCOLLAB_CONFIG can override config path.
+  SUPERCOLLAB_MODEL_CACHE can override the local Hugging Face model cache.
   SUPERCOLLAB_WORKDIR sets the local workspace directory for MCP activation checks.
 `);
 }
@@ -363,6 +368,78 @@ async function doLogin(config, file, opts) {
   return { ok: true, username: config.username, user_id: config.userId, config: file };
 }
 
+function commandExists(command, args = ['--version']) {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return {
+    ok: result.status === 0,
+    command,
+    status: result.status,
+    output: String(result.stdout || result.stderr || '').trim().split('\n')[0] || '',
+  };
+}
+
+function installAdvice(profile, checks = {}) {
+  const advice = [];
+  const platform = profile.platform;
+  if (!checks.node_supported?.ok) {
+    advice.push('Install Node.js 20 LTS or newer, then reinstall @supercollab/cli.');
+  }
+  if (!checks.native_sqlite_vec?.ok) {
+    if (profile.tools?.npm_ignore_scripts?.output === 'true') {
+      advice.push('Your npm config has `ignore-scripts=true`, which prevents native SQLite from installing. Run `npm config set ignore-scripts false`, then reinstall or run `npm rebuild -g better-sqlite3 --ignore-scripts=false`.');
+    }
+    if (platform === 'darwin') {
+      advice.push('Install Apple command line tools with `xcode-select --install`, then run `npm rebuild -g better-sqlite3`.');
+    } else if (platform === 'linux') {
+      advice.push('Install Python 3, make, and a C/C++ compiler, then run `npm rebuild -g better-sqlite3`.');
+    } else if (platform === 'win32') {
+      advice.push('Install Microsoft Visual Studio Build Tools with the C++ workload and Python, then run `npm rebuild -g better-sqlite3`.');
+    } else {
+      advice.push('Install a native build toolchain for your OS, then run `npm rebuild -g better-sqlite3`.');
+    }
+  }
+  if (!checks.bge_model?.ok && checks.bge_model?.error) {
+    advice.push('Check internet access to Hugging Face model downloads, then run `supercollab embeddings warmup`.');
+  }
+  return advice;
+}
+
+function detectSystemProfile() {
+  const cpus = os.cpus() || [];
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  const tools = {
+    npm: commandExists('npm', ['--version']),
+    npm_ignore_scripts: commandExists('npm', ['config', 'get', 'ignore-scripts']),
+  };
+  if (process.platform === 'darwin') {
+    tools.xcode_select = commandExists('xcode-select', ['-p']);
+    tools.clang = commandExists('clang', ['--version']);
+  } else if (process.platform === 'linux') {
+    tools.python3 = commandExists('python3', ['--version']);
+    tools.make = commandExists('make', ['--version']);
+    tools.cc = commandExists('cc', ['--version']);
+    tools.gpp = commandExists('g++', ['--version']);
+  } else if (process.platform === 'win32') {
+    tools.python = commandExists('python', ['--version']);
+    tools.node_gyp = commandExists('node-gyp', ['--version']);
+  }
+  return {
+    detected_at: nowIso(),
+    cli_version: VERSION,
+    platform: process.platform,
+    arch: process.arch,
+    os_type: os.type(),
+    os_release: os.release(),
+    hostname: os.hostname(),
+    node: process.versions.node,
+    node_modules_abi: process.versions.modules,
+    node_supported: nodeMajor >= 20,
+    cpu_model: cpus[0]?.model || null,
+    cpu_count: cpus.length,
+    tools,
+  };
+}
+
 let nativeSqlitePromise = null;
 
 async function loadNativeSqlite() {
@@ -1094,14 +1171,14 @@ async function runMcp(opts) {
 
 function printCodexConfig(opts) {
   const file = configPath(opts);
-  console.log(`[mcp_servers.supercollab]\ncommand = "supercollab"\nargs = ["mcp", "stdio", "--config", "${file.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"]`);
+  console.log(mcpConfigText(String(opts.client || 'codex'), file));
 }
 
 async function embeddingStatus() {
   return {
     ok: true,
     profile: EMBEDDING_PROFILE,
-    model_download: 'lazy on first embedding, or now via `supercollab embeddings warmup`',
+    model_download: 'installed during setup, or manually via `supercollab embeddings warmup`',
     cache_dir: process.env.SUPERCOLLAB_MODEL_CACHE || 'default @huggingface/transformers cache',
   };
 }
@@ -1115,14 +1192,1100 @@ async function embeddingWarmup() {
   };
 }
 
+async function nativeEngineCheck() {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'supercollab-doctor-'));
+  const dbPath = path.join(tempDir, 'native.sqlite');
+  let db = null;
+  try {
+    const { Database, sqliteVec } = await loadNativeSqlite();
+    db = new Database(dbPath);
+    sqliteVec.load(db);
+    const version = db.prepare('SELECT vec_version() AS version').get()?.version;
+    db.exec(`CREATE VIRTUAL TABLE vec_check USING vec0(id TEXT PRIMARY KEY, embedding float[${EMBEDDING_DIMS}] distance_metric=cosine)`);
+    db.prepare('INSERT INTO vec_check(id, embedding) VALUES(?, ?)').run('ok', new Float32Array(new Array(EMBEDDING_DIMS).fill(0).map((_, i) => i === 0 ? 1 : 0)));
+    const rows = db.prepare('SELECT id, distance FROM vec_check WHERE embedding MATCH ? AND k = 1').all(new Float32Array(new Array(EMBEDDING_DIMS).fill(0).map((_, i) => i === 0 ? 1 : 0)));
+    if (rows[0]?.id !== 'ok') throw new Error('sqlite-vec query did not return expected row');
+    return {
+      ok: true,
+      engine: 'native-sqlite-vec',
+      sqlite_vec_version: version,
+      dims: EMBEDDING_DIMS,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      engine: 'native-sqlite-vec',
+      error: err.message || String(err),
+    };
+  } finally {
+    try { db?.close(); } catch {}
+    try { fs.rmSync(tempDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+async function runDoctor(config, file, opts = {}) {
+  const profile = detectSystemProfile();
+  const checks = {
+    node_supported: {
+      ok: profile.node_supported,
+      version: profile.node,
+      required: '>=20',
+    },
+    native_sqlite_vec: await nativeEngineCheck(),
+  };
+
+  if (!opts['skip-model']) {
+    try {
+      const warmed = await embeddingWarmup();
+      checks.bge_model = {
+        ok: warmed.ok && warmed.dims === EMBEDDING_DIMS,
+        dims: warmed.dims,
+        profile: EMBEDDING_PROFILE,
+        cache_dir: process.env.SUPERCOLLAB_MODEL_CACHE || 'default @huggingface/transformers cache',
+      };
+    } catch (err) {
+      checks.bge_model = {
+        ok: false,
+        profile: EMBEDDING_PROFILE,
+        error: err.message || String(err),
+      };
+    }
+  } else {
+    checks.bge_model = {
+      ok: null,
+      skipped: true,
+      profile: EMBEDDING_PROFILE,
+    };
+  }
+
+  const ok = checks.node_supported.ok && checks.native_sqlite_vec.ok && (checks.bge_model.ok === true || checks.bge_model.skipped === true);
+  const result = {
+    ok,
+    checked_at: nowIso(),
+    system: profile,
+    checks,
+    local_engine: {
+      id: 'native-sqlite-vec',
+      transcript_store: 'better-sqlite3',
+      vector_store: 'sqlite-vec',
+      vector_version: checks.native_sqlite_vec.sqlite_vec_version || null,
+      embedding_profile_id: EMBEDDING_PROFILE.id,
+    },
+    advice: installAdvice(profile, checks),
+  };
+
+  config.systemProfile = profile;
+  config.localEngine = result.local_engine;
+  config.embeddingProfile = EMBEDDING_PROFILE;
+  config.setupChecks = {
+    ok,
+    checked_at: result.checked_at,
+    checks,
+    advice: result.advice,
+  };
+  saveConfig(config, file);
+  return result;
+}
+
+function printDoctor(result) {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function loadPrompts() {
+  return import('@clack/prompts');
+}
+
+function isConfigured(config) {
+  return Boolean(config.userToken && config.agentId && config.agentPrivateKeyPem);
+}
+
+function promptRequired(value) {
+  return String(value || '').trim() ? undefined : 'Required';
+}
+
+function trimmed(value) {
+  return String(value || '').trim();
+}
+
+function shorten(value, max = 80) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+
+function roomIdFrom(room) {
+  return trimmed(room?.room_id || room?.id || room?.workspace_id);
+}
+
+function roomTitleFrom(room) {
+  return trimmed(room?.title || room?.name || room?.slug || room?.goal || roomIdFrom(room));
+}
+
+function roomsFromResponse(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.rooms)) return data.rooms;
+  if (Array.isArray(data?.workspaces)) return data.workspaces;
+  if (Array.isArray(data?.items)) return data.items;
+  return [];
+}
+
+function hasLocalRoomKey(config, roomId) {
+  return Boolean(config.roomKeys?.[roomId]);
+}
+
+function roomLabel(room, config) {
+  const roomId = roomIdFrom(room);
+  const title = roomTitleFrom(room);
+  const prefix = title && title !== roomId ? `${shorten(title, 42)} ` : '';
+  const key = hasLocalRoomKey(config, roomId) ? 'key saved' : 'key missing';
+  return `${prefix}(${roomId})`;
+}
+
+function roomHint(room, config) {
+  const roomId = roomIdFrom(room);
+  const pieces = [];
+  const goal = trimmed(room?.goal || room?.description);
+  if (goal) pieces.push(shorten(goal, 48));
+  pieces.push(hasLocalRoomKey(config, roomId) ? 'encrypted local search ready' : 'join/import key to decrypt');
+  return pieces.join(' - ');
+}
+
+async function listRoomsForMenu(config) {
+  const data = await apiAsAgent(config, 'GET', '/v1/rooms');
+  return roomsFromResponse(data).filter((room) => roomIdFrom(room));
+}
+
+async function promptManualRoomId(prompts, message = 'Room ID') {
+  const roomId = await prompts.text({
+    message,
+    placeholder: 'room_...',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(roomId)) throw new Error('cancelled');
+  return trimmed(roomId);
+}
+
+async function ensureRoomKeyFromMenu(config, file, prompts, roomId) {
+  try {
+    ensureRoomKey(config, roomId);
+    return true;
+  } catch {
+    const choice = await prompts.select({
+      message: `No local room key for ${roomId}`,
+      options: [
+        { value: 'invite', label: 'Join with private invite', hint: 'recommended if another member invited you' },
+        { value: 'key', label: 'Paste room key', hint: 'sck_... from a trusted device' },
+        { value: 'choose', label: 'Choose another room' },
+        { value: 'cancel', label: 'Cancel' },
+      ],
+    });
+    if (prompts.isCancel(choice) || choice === 'cancel') throw new Error('cancelled');
+    if (choice === 'choose') return false;
+    if (choice === 'invite') {
+      const joined = await promptJoinRoom(config, file, prompts, { quiet: true });
+      return Boolean(joined?.room_id === roomId || joined?.workspace_id === roomId || hasLocalRoomKey(config, roomId));
+    }
+    const key = await prompts.text({
+      message: 'Paste room key',
+      placeholder: 'sck_...',
+      validate: (value) => {
+        try {
+          roomKeyBytes(trimmed(value));
+          return undefined;
+        } catch {
+          return 'Invalid room key';
+        }
+      },
+    });
+    if (prompts.isCancel(key)) throw new Error('cancelled');
+    storeRoomKey(config, roomId, trimmed(key));
+    saveConfig(config, file);
+    return true;
+  }
+}
+
+async function selectRoom(config, file, prompts, options = {}) {
+  const {
+    message = 'Choose room',
+    requireKey = true,
+    includeCreate = false,
+    includeJoin = false,
+    includeManual = true,
+  } = options;
+
+  while (true) {
+    let rooms = [];
+    try {
+      rooms = await listRoomsForMenu(config);
+    } catch (err) {
+      prompts.note(err.message || String(err), 'Could not load rooms');
+    }
+
+    const choices = rooms.map((room) => ({
+      value: roomIdFrom(room),
+      label: roomLabel(room, config),
+      hint: roomHint(room, config),
+    }));
+    if (includeCreate) choices.push({ value: '__create', label: 'Create new room', hint: 'set title and goal now' });
+    if (includeJoin) choices.push({ value: '__join', label: 'Join with private invite', hint: 'paste sci_...sck_...' });
+    if (includeManual) choices.push({ value: '__manual', label: 'Type room ID manually', hint: 'room_...' });
+    choices.push({ value: '__back', label: 'Back' });
+
+    const selected = await prompts.select({ message, options: choices });
+    if (prompts.isCancel(selected) || selected === '__back') throw new Error('cancelled');
+
+    if (selected === '__create') {
+      const created = await promptCreateRoom(config, file, prompts, { quiet: true });
+      if (created?.room_id) return created.room_id;
+      continue;
+    }
+    if (selected === '__join') {
+      const joined = await promptJoinRoom(config, file, prompts, { quiet: true });
+      const joinedRoomId = joined?.room_id || joined?.workspace_id;
+      if (joinedRoomId) return joinedRoomId;
+      continue;
+    }
+
+    const roomId = selected === '__manual'
+      ? await promptManualRoomId(prompts)
+      : String(selected);
+
+    if (!requireKey) return roomId;
+    const ok = await ensureRoomKeyFromMenu(config, file, prompts, roomId);
+    if (ok) return roomId;
+  }
+}
+
+function formatMessagesForNote(messages, maxRows = 12) {
+  const rows = (messages || []).slice(-maxRows);
+  if (!rows.length) return 'No messages yet.';
+  return rows.map((row) => {
+    const when = trimmed(row.created_at).replace('T', ' ').replace('Z', '');
+    return `[${when}] ${row.sender_label || row.actor_id || 'agent'}\n${shorten(row.body, 260)}`;
+  }).join('\n\n');
+}
+
+function formatSearchForNote(results, maxRows = 8) {
+  const rows = (results || []).slice(0, maxRows);
+  if (!rows.length) return 'No matching messages.';
+  return rows.map((row, idx) => {
+    const sources = Array.isArray(row.search_sources) ? row.search_sources.join('+') : 'match';
+    return `${idx + 1}. ${row.sender_label || row.actor_id || 'agent'} - ${sources}\n${shorten(row.body, 260)}`;
+  }).join('\n\n');
+}
+
+async function promptCreateRoom(config, file, prompts, options = {}) {
+  const title = await prompts.text({
+    message: 'Room title',
+    placeholder: 'Launch Room',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(title)) throw new Error('cancelled');
+  const goal = await prompts.text({
+    message: 'Room goal',
+    placeholder: 'Coordinate agents on this project',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(goal)) throw new Error('cancelled');
+  const slug = await prompts.text({
+    message: 'Optional short slug',
+    placeholder: 'press Enter to skip',
+  });
+  if (prompts.isCancel(slug)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Creating encrypted room');
+  try {
+    const created = await doRoomCreate(config, file, {
+      title: trimmed(title),
+      goal: trimmed(goal),
+      slug: trimmed(slug) || undefined,
+    });
+    const roomId = created.room_id || created.id;
+    spin.stop(`Room created: ${roomId}`);
+    if (!options.quiet) prompts.note(`Room ID: ${roomId}\nLocal room key: saved on this machine`, 'Room created');
+    return { ...created, room_id: roomId };
+  } catch (err) {
+    spin.stop('Room creation failed');
+    throw err;
+  }
+}
+
+async function promptJoinRoom(config, file, prompts, options = {}) {
+  const invite = await prompts.text({
+    message: 'Paste private invite',
+    placeholder: 'sci_....sck_...',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(invite)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Joining room and saving local room key');
+  try {
+    const joined = await doRoomJoin(config, file, { invite: trimmed(invite) });
+    const roomId = joined.room_id || joined.workspace_id;
+    spin.stop(`Joined room: ${roomId}`);
+    if (!options.quiet) prompts.note(`Room ID: ${roomId}\nLocal room key saved: ${joined.room_key_saved ? 'yes' : 'no'}`, 'Joined');
+    return { ...joined, room_id: roomId };
+  } catch (err) {
+    spin.stop('Join failed');
+    throw err;
+  }
+}
+
+async function ensureAgentForSetup(config, file, prompts) {
+  if (config.agentId && config.agentPrivateKeyPem) return null;
+  const label = await prompts.text({
+    message: 'Name this local agent',
+    placeholder: `${os.hostname()}-agent`,
+    defaultValue: `${os.hostname()}-agent`,
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(label)) throw new Error('cancelled');
+  const agent = await registerAgent(config, String(label));
+  saveConfig(config, file);
+  return agent;
+}
+
+async function runAuthSetup(config, file, prompts) {
+  if (isConfigured(config)) {
+    const reuse = await prompts.confirm({
+      message: `Use existing login as ${config.username || 'current user'}?`,
+      initialValue: true,
+    });
+    if (prompts.isCancel(reuse)) throw new Error('cancelled');
+    if (reuse) return { reused: true };
+  }
+
+  const mode = await prompts.select({
+    message: 'Account setup',
+    options: [
+      { value: 'register', label: 'Create account', hint: 'new SuperCollab username' },
+      { value: 'login', label: 'Log in', hint: 'existing username' },
+    ],
+  });
+  if (prompts.isCancel(mode)) throw new Error('cancelled');
+
+  const username = await prompts.text({
+    message: mode === 'register' ? 'Choose a username' : 'Username',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(username)) throw new Error('cancelled');
+
+  const pass = await prompts.password({
+    message: mode === 'register' ? 'Choose a password' : 'Password',
+    validate: (value) => String(value || '').length >= 8 ? undefined : 'Use at least 8 characters',
+  });
+  if (prompts.isCancel(pass)) throw new Error('cancelled');
+
+  if (mode === 'register') {
+    return doRegister(config, file, { username: String(username), password: String(pass), label: `${os.hostname()}-agent` });
+  }
+
+  const login = await doLogin(config, file, { username: String(username), password: String(pass) });
+  const agent = await ensureAgentForSetup(config, file, prompts);
+  return { ...login, agent_id: agent?.agent_id || config.agentId, fingerprint: agent?.fingerprint || config.agentFingerprint };
+}
+
+async function runRoomSetup(config, file, prompts) {
+  const choice = await prompts.select({
+    message: 'Room setup',
+    options: [
+      { value: 'existing', label: 'Use an existing room', hint: 'pick from your rooms or type a room ID' },
+      { value: 'create', label: 'Create a new room', hint: 'start solo or invite agents later' },
+      { value: 'join', label: 'Join with private invite', hint: 'paste sci_...sck_...' },
+      { value: 'skip', label: 'Skip for now', hint: 'set up auth and local engine only' },
+    ],
+  });
+  if (prompts.isCancel(choice)) throw new Error('cancelled');
+  if (choice === 'skip') return null;
+
+  if (choice === 'existing') {
+    const roomId = await selectRoom(config, file, prompts, {
+      message: 'Choose room to use',
+      requireKey: true,
+      includeCreate: true,
+      includeJoin: true,
+    });
+    return { room_id: roomId, existing: true };
+  }
+
+  if (choice === 'join') {
+    const joined = await promptJoinRoom(config, file, prompts, { quiet: true });
+    return { room_id: joined.room_id || joined.workspace_id, joined };
+  }
+
+  const created = await promptCreateRoom(config, file, prompts, { quiet: true });
+  return { room_id: created.room_id || created.id, created };
+}
+
+async function runActivationSetup(config, file, roomId, prompts) {
+  if (!roomId) {
+    const pick = await prompts.confirm({
+      message: 'Activate an existing room for this project directory?',
+      initialValue: false,
+    });
+    if (prompts.isCancel(pick)) throw new Error('cancelled');
+    if (!pick) return null;
+    roomId = await selectRoom(config, file, prompts, {
+      message: 'Choose room to activate',
+      requireKey: true,
+      includeCreate: true,
+      includeJoin: true,
+    });
+  }
+  const shouldActivate = await prompts.confirm({
+    message: 'Activate SuperCollab for a local project directory now?',
+    initialValue: true,
+  });
+  if (prompts.isCancel(shouldActivate)) throw new Error('cancelled');
+  if (!shouldActivate) return null;
+  const cwd = await prompts.text({
+    message: 'Project directory',
+    defaultValue: process.cwd(),
+    placeholder: process.cwd(),
+    validate: (value) => {
+      const resolved = path.resolve(String(value || ''));
+      return fs.existsSync(resolved) ? undefined : 'Directory does not exist';
+    },
+  });
+  if (prompts.isCancel(cwd)) throw new Error('cancelled');
+  return activate(config, file, { room: roomId, cwd: String(cwd) });
+}
+
+async function runSetupSmoke(config, file, roomId, prompts) {
+  if (!roomId) return null;
+  const shouldSmoke = await prompts.confirm({
+    message: 'Send a setup note and verify local BGE search?',
+    initialValue: true,
+  });
+  if (prompts.isCancel(shouldSmoke)) throw new Error('cancelled');
+  if (!shouldSmoke) return null;
+  const marker = `setup-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+  const text = `SuperCollab setup complete on ${os.hostname()} (${marker})`;
+  await doChatSend(config, file, { room: roomId, text, channel: 'agents', kind: 'setup.note' });
+  const search = await doChatSearch(config, file, { room: roomId, query: marker, mode: 'hybrid', limit: 5 });
+  return {
+    ok: search.results.some((row) => String(row.body || '').includes(marker)),
+    marker,
+    search_count: search.results.length,
+  };
+}
+
+function mcpConfigText(client, file) {
+  const escaped = file.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+  if (client === 'claude') {
+    return JSON.stringify({
+      mcpServers: {
+        supercollab: {
+          command: 'supercollab',
+          args: ['mcp', 'stdio', '--config', file],
+        },
+      },
+    }, null, 2);
+  }
+  if (client === 'codex') {
+    return `[mcp_servers.supercollab]\ncommand = "supercollab"\nargs = ["mcp", "stdio", "--config", "${escaped}"]`;
+  }
+  return `supercollab mcp stdio --config "${escaped}"`;
+}
+
+async function promptSystemCheck(config, file, prompts) {
+  const spin = prompts.spinner();
+  spin.start('Checking this machine and warming the local BGE model');
+  const doctor = await runDoctor(config, file, {});
+  spin.stop(doctor.ok ? 'Local engine ready' : 'Local engine needs attention');
+  const checks = [
+    `Node: ${doctor.checks.node_supported.ok ? 'ok' : 'needs Node >=20'} (${doctor.system.node})`,
+    `SQLite vector engine: ${doctor.checks.native_sqlite_vec.ok ? 'ok' : 'failed'}${doctor.checks.native_sqlite_vec.sqlite_vec_version ? ` (${doctor.checks.native_sqlite_vec.sqlite_vec_version})` : ''}`,
+    `BGE model: ${doctor.checks.bge_model.ok ? 'ok' : doctor.checks.bge_model.skipped ? 'skipped' : 'failed'}`,
+    `Embedding profile: ${doctor.local_engine.embedding_profile_id}`,
+  ];
+  if (doctor.advice?.length) checks.push('', ...doctor.advice);
+  prompts.note(checks.join('\n'), doctor.ok ? 'Doctor passed' : 'Doctor');
+  return doctor;
+}
+
+async function promptActivateRoom(config, file, prompts, options = {}) {
+  const roomId = options.roomId || await selectRoom(config, file, prompts, {
+    message: 'Choose room to activate',
+    requireKey: true,
+    includeCreate: true,
+    includeJoin: true,
+  });
+  const cwd = await prompts.text({
+    message: 'Project directory',
+    defaultValue: options.cwd || process.cwd(),
+    placeholder: options.cwd || process.cwd(),
+    validate: (value) => {
+      const resolved = path.resolve(String(value || ''));
+      return fs.existsSync(resolved) ? undefined : 'Directory does not exist';
+    },
+  });
+  if (prompts.isCancel(cwd)) throw new Error('cancelled');
+  const activation = activate(config, file, { room: roomId, cwd: String(cwd) });
+  prompts.note(`${activation.instructions}\n\nActivation root: ${activation.cwd}`, 'Workspace active');
+  return activation;
+}
+
+async function promptDeactivateRoom(config, file, prompts, options = {}) {
+  const cwd = await prompts.text({
+    message: 'Directory to deactivate',
+    defaultValue: options.cwd || process.cwd(),
+    placeholder: options.cwd || process.cwd(),
+    validate: (value) => fs.existsSync(path.resolve(String(value || ''))) ? undefined : 'Directory does not exist',
+  });
+  if (prompts.isCancel(cwd)) throw new Error('cancelled');
+  const result = deactivate(config, file, { cwd: String(cwd) });
+  prompts.note(`SuperCollab is off for ${result.cwd}`, 'Workspace deactivated');
+  return result;
+}
+
+async function promptCreateInvite(config, file, prompts, options = {}) {
+  const roomId = options.roomId || await selectRoom(config, file, prompts, {
+    message: 'Choose room to invite into',
+    requireKey: true,
+    includeCreate: true,
+    includeJoin: false,
+  });
+  const role = await prompts.select({
+    message: 'Invite role',
+    options: [
+      { value: 'member', label: 'Member', hint: 'normal agent/user access' },
+    ],
+  });
+  if (prompts.isCancel(role)) throw new Error('cancelled');
+  const ttl = await prompts.select({
+    message: 'Invite expiry',
+    options: [
+      { value: 86400, label: '24 hours' },
+      { value: 3600, label: '1 hour' },
+      { value: 604800, label: '7 days' },
+    ],
+  });
+  if (prompts.isCancel(ttl)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Creating private invite');
+  try {
+    const data = await doRoomInvite(config, { room: roomId, role, ttl_seconds: ttl });
+    spin.stop('Private invite created');
+    prompts.note(data.private_invite, 'Share this private invite');
+    return data;
+  } catch (err) {
+    spin.stop('Invite failed');
+    throw err;
+  }
+}
+
+async function promptSendMessage(config, file, prompts, options = {}) {
+  const roomId = options.roomId || await selectRoom(config, file, prompts, {
+    message: 'Choose room to message',
+    requireKey: true,
+    includeCreate: true,
+    includeJoin: true,
+  });
+  let channel = await prompts.select({
+    message: 'Channel',
+    options: [
+      { value: 'agents', label: 'Agents', hint: 'default coordination chat' },
+      { value: 'progress', label: 'Progress', hint: 'status notes' },
+      { value: 'decisions', label: 'Decisions', hint: 'architecture/product decisions' },
+      { value: 'blockers', label: 'Blockers', hint: 'things that need attention' },
+      { value: '__custom', label: 'Type custom channel' },
+    ],
+  });
+  if (prompts.isCancel(channel)) throw new Error('cancelled');
+  if (channel === '__custom') {
+    channel = await prompts.text({ message: 'Channel name', validate: promptRequired });
+    if (prompts.isCancel(channel)) throw new Error('cancelled');
+  }
+  const kind = await prompts.select({
+    message: 'Message type',
+    options: [
+      { value: 'chat.message', label: 'Chat message' },
+      { value: 'progress.note', label: 'Progress note' },
+      { value: 'decision.note', label: 'Decision note' },
+      { value: 'blocker.note', label: 'Blocker note' },
+    ],
+  });
+  if (prompts.isCancel(kind)) throw new Error('cancelled');
+  const text = await prompts.text({
+    message: 'Message',
+    placeholder: 'Concise agent-to-agent note',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(text)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Encrypting, uploading, and indexing locally');
+  try {
+    const data = await doChatSend(config, file, {
+      room: roomId,
+      text: String(text),
+      channel: trimmed(channel) || 'agents',
+      kind,
+    });
+    spin.stop('Message sent');
+    prompts.note(`Room: ${roomId}\nMessage ID: ${data.message?.message_id || data.message?.id || 'saved'}`, 'Sent');
+    return data;
+  } catch (err) {
+    spin.stop('Send failed');
+    throw err;
+  }
+}
+
+async function promptReadMessages(config, file, prompts, options = {}) {
+  const roomId = options.roomId || await selectRoom(config, file, prompts, {
+    message: 'Choose room to read',
+    requireKey: true,
+    includeCreate: false,
+    includeJoin: true,
+  });
+  const limit = await prompts.select({
+    message: 'How many recent messages?',
+    options: [
+      { value: 20, label: '20 messages' },
+      { value: 50, label: '50 messages' },
+      { value: 100, label: '100 messages' },
+      { value: 200, label: '200 messages' },
+    ],
+  });
+  if (prompts.isCancel(limit)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Syncing and decrypting transcript locally');
+  try {
+    const data = await doChatRead(config, file, { room: roomId, limit });
+    spin.stop(`Read ${data.messages.length} local messages`);
+    prompts.note(formatMessagesForNote(data.messages), `Recent messages (${roomId})`);
+    return data;
+  } catch (err) {
+    spin.stop('Read failed');
+    throw err;
+  }
+}
+
+async function promptSearchMessages(config, file, prompts, options = {}) {
+  const roomId = options.roomId || await selectRoom(config, file, prompts, {
+    message: 'Choose room to search',
+    requireKey: true,
+    includeCreate: false,
+    includeJoin: true,
+  });
+  const query = await prompts.text({
+    message: 'Search query',
+    placeholder: 'auth decisions, current blocker, setup note...',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(query)) throw new Error('cancelled');
+  const mode = await prompts.select({
+    message: 'Search mode',
+    options: [
+      { value: 'hybrid', label: 'Hybrid', hint: 'keyword + BGE vector' },
+      { value: 'keyword', label: 'Keyword', hint: 'SQLite FTS/BM25' },
+      { value: 'vector', label: 'Vector', hint: 'local BGE cosine search' },
+    ],
+  });
+  if (prompts.isCancel(mode)) throw new Error('cancelled');
+  const limit = await prompts.select({
+    message: 'Result limit',
+    options: [
+      { value: 10, label: '10 results' },
+      { value: 20, label: '20 results' },
+      { value: 50, label: '50 results' },
+    ],
+  });
+  if (prompts.isCancel(limit)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Syncing, embedding locally, and searching');
+  try {
+    const data = await doChatSearch(config, file, { room: roomId, query: String(query), mode, limit });
+    spin.stop(`Found ${data.results.length} result(s)`);
+    prompts.note(formatSearchForNote(data.results), `Search results (${mode})`);
+    return data;
+  } catch (err) {
+    spin.stop('Search failed');
+    throw err;
+  }
+}
+
+async function promptSyncRoom(config, file, prompts, options = {}) {
+  const roomId = options.roomId || await selectRoom(config, file, prompts, {
+    message: 'Choose room to sync',
+    requireKey: true,
+    includeCreate: false,
+    includeJoin: true,
+  });
+  const spin = prompts.spinner();
+  spin.start('Syncing encrypted room transcript into local SQLite');
+  try {
+    const data = await syncRoom(config, file, roomId);
+    spin.stop(`Pulled ${data.pulled} message(s)`);
+    prompts.note(`Local DB: ${data.db}\nLast message ID: ${data.last_message_id}\nChunks embedded: ${data.embedding?.chunks_embedded || 0}`, 'Sync complete');
+    return data;
+  } catch (err) {
+    spin.stop('Sync failed');
+    throw err;
+  }
+}
+
+async function promptRoomActions(config, file, prompts, roomId) {
+  while (true) {
+    const action = await prompts.select({
+      message: `Room ${roomId}`,
+      options: [
+        { value: 'activate', label: 'Activate for a project directory' },
+        { value: 'invite', label: 'Create private invite' },
+        { value: 'send', label: 'Send message' },
+        { value: 'read', label: 'Read recent messages' },
+        { value: 'search', label: 'Search transcript' },
+        { value: 'sync', label: 'Sync locally' },
+        { value: 'back', label: 'Back' },
+      ],
+    });
+    if (prompts.isCancel(action) || action === 'back') return;
+    try {
+      if (action === 'activate') await promptActivateRoom(config, file, prompts, { roomId });
+      if (action === 'invite') await promptCreateInvite(config, file, prompts, { roomId });
+      if (action === 'send') await promptSendMessage(config, file, prompts, { roomId });
+      if (action === 'read') await promptReadMessages(config, file, prompts, { roomId });
+      if (action === 'search') await promptSearchMessages(config, file, prompts, { roomId });
+      if (action === 'sync') await promptSyncRoom(config, file, prompts, { roomId });
+    } catch (err) {
+      if (err.message !== 'cancelled') prompts.note(err.message || String(err), 'Action failed');
+    }
+  }
+}
+
+async function promptBrowseRooms(config, file, prompts) {
+  const roomId = await selectRoom(config, file, prompts, {
+    message: 'Choose room',
+    requireKey: false,
+    includeCreate: true,
+    includeJoin: true,
+    includeManual: true,
+  });
+  const ok = await ensureRoomKeyFromMenu(config, file, prompts, roomId);
+  if (!ok) return promptBrowseRooms(config, file, prompts);
+  return promptRoomActions(config, file, prompts, roomId);
+}
+
+async function promptAccountStatus(config, file, prompts) {
+  let me = null;
+  try {
+    me = config.userToken ? await api(config, 'GET', '/v1/me', undefined, config.userToken) : null;
+  } catch {}
+  const active = await activeStatus(config, file, {});
+  const rooms = await listRoomsForMenu(config).catch(() => []);
+  const lines = [
+    `Server: ${config.serverUrl || DEFAULT_SERVER}`,
+    `User: ${config.username || me?.username || 'not logged in'}`,
+    `Agent: ${config.agentLabel || config.agentId || 'not registered'}`,
+    `Fingerprint: ${config.agentFingerprint || 'none'}`,
+    `Rooms visible: ${rooms.length}`,
+    `Current directory: ${active.active ? `active in ${active.room_id}` : 'SuperCollab off'}`,
+    `Config: ${file}`,
+  ];
+  prompts.note(lines.join('\n'), 'Account and config');
+}
+
+async function promptMcpConfig(config, file, prompts) {
+  const client = await prompts.select({
+    message: 'MCP client config',
+    options: [
+      { value: 'codex', label: 'Codex', hint: 'TOML config snippet' },
+      { value: 'claude', label: 'Claude', hint: 'JSON config snippet' },
+      { value: 'manual', label: 'Manual', hint: 'stdio command' },
+      { value: 'back', label: 'Back' },
+    ],
+  });
+  if (prompts.isCancel(client) || client === 'back') return;
+  prompts.note(mcpConfigText(client, file), `${client} MCP config`);
+}
+
+function sessionsFromResponse(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.sessions)) return data.sessions;
+  if (Array.isArray(data?.items)) return data.items;
+  return [];
+}
+
+function sessionIdFrom(session) {
+  return trimmed(session?.session_id || session?.id || session?.token_id);
+}
+
+async function promptManageSessions(config, prompts) {
+  const data = await api(config, 'GET', '/v1/agent-sessions', undefined, config.userToken);
+  const sessions = sessionsFromResponse(data).filter((session) => sessionIdFrom(session));
+  if (!sessions.length) {
+    prompts.note('No active sessions returned by the server.', 'Sessions');
+    return;
+  }
+  const selected = await prompts.select({
+    message: 'Choose session to revoke',
+    options: [
+      ...sessions.map((session) => {
+        const id = sessionIdFrom(session);
+        const label = `${shorten(session.agent_label || session.label || id, 36)} (${id})`;
+        const hint = [session.created_at, session.expires_at ? `expires ${session.expires_at}` : null].filter(Boolean).join(' - ');
+        return { value: id, label, hint };
+      }),
+      { value: '__manual', label: 'Type session ID manually' },
+      { value: '__back', label: 'Back' },
+    ],
+  });
+  if (prompts.isCancel(selected) || selected === '__back') return;
+  const sessionId = selected === '__manual'
+    ? await prompts.text({ message: 'Session ID', validate: promptRequired })
+    : selected;
+  if (prompts.isCancel(sessionId)) throw new Error('cancelled');
+  const confirm = await prompts.confirm({ message: `Revoke session ${sessionId}?`, initialValue: false });
+  if (prompts.isCancel(confirm) || !confirm) return;
+  await api(config, 'DELETE', `/v1/agent-sessions/${encodeURIComponent(String(sessionId))}`, undefined, config.userToken);
+  prompts.note(`Revoked ${sessionId}`, 'Session revoked');
+}
+
+async function promptSetServerUrl(config, file, prompts) {
+  const server = await prompts.text({
+    message: 'SuperCollab server URL',
+    defaultValue: config.serverUrl || DEFAULT_SERVER,
+    placeholder: DEFAULT_SERVER,
+    validate: (value) => {
+      try {
+        const parsed = new URL(String(value || ''));
+        return parsed.protocol === 'https:' || parsed.hostname === 'localhost' ? undefined : 'Use https:// for remote servers';
+      } catch {
+        return 'Enter a valid URL';
+      }
+    },
+  });
+  if (prompts.isCancel(server)) throw new Error('cancelled');
+  config.serverUrl = trimmed(server).replace(/\/$/, '');
+  saveConfig(config, file);
+  prompts.note(config.serverUrl, 'Server URL saved');
+}
+
+async function runRoomsMenu(config, file, prompts) {
+  while (true) {
+    const action = await prompts.select({
+      message: 'Rooms',
+      options: [
+        { value: 'browse', label: 'Browse/select room', hint: 'scroll rooms or type room ID' },
+        { value: 'create', label: 'Create room', hint: 'sets up backend room and local key' },
+        { value: 'join', label: 'Join with private invite', hint: 'saves room key locally' },
+        { value: 'invite', label: 'Create private invite' },
+        { value: 'back', label: 'Back' },
+      ],
+    });
+    if (prompts.isCancel(action) || action === 'back') return;
+    try {
+      if (action === 'browse') await promptBrowseRooms(config, file, prompts);
+      if (action === 'create') {
+        const created = await promptCreateRoom(config, file, prompts);
+        if (created?.room_id) await promptRoomActions(config, file, prompts, created.room_id);
+      }
+      if (action === 'join') {
+        const joined = await promptJoinRoom(config, file, prompts);
+        if (joined?.room_id) await promptRoomActions(config, file, prompts, joined.room_id);
+      }
+      if (action === 'invite') await promptCreateInvite(config, file, prompts);
+    } catch (err) {
+      if (err.message !== 'cancelled') prompts.note(err.message || String(err), 'Room action failed');
+    }
+  }
+}
+
+async function runChatMenu(config, file, prompts) {
+  while (true) {
+    const action = await prompts.select({
+      message: 'Chat',
+      options: [
+        { value: 'send', label: 'Send message/note' },
+        { value: 'read', label: 'Read recent messages' },
+        { value: 'search', label: 'Search transcript' },
+        { value: 'sync', label: 'Sync room locally' },
+        { value: 'back', label: 'Back' },
+      ],
+    });
+    if (prompts.isCancel(action) || action === 'back') return;
+    try {
+      if (action === 'send') await promptSendMessage(config, file, prompts);
+      if (action === 'read') await promptReadMessages(config, file, prompts);
+      if (action === 'search') await promptSearchMessages(config, file, prompts);
+      if (action === 'sync') await promptSyncRoom(config, file, prompts);
+    } catch (err) {
+      if (err.message !== 'cancelled') prompts.note(err.message || String(err), 'Chat action failed');
+    }
+  }
+}
+
+async function runWorkspaceMenu(config, file, prompts) {
+  while (true) {
+    const active = await activeStatus(config, file, {});
+    const action = await prompts.select({
+      message: `Workspace activation (${active.active ? `active: ${active.room_id}` : 'off'})`,
+      options: [
+        { value: 'status', label: 'Show current status' },
+        { value: 'activate', label: 'Activate this directory' },
+        { value: 'activate_other', label: 'Activate another directory' },
+        { value: 'deactivate', label: 'Deactivate directory' },
+        { value: 'back', label: 'Back' },
+      ],
+    });
+    if (prompts.isCancel(action) || action === 'back') return;
+    try {
+      if (action === 'status') prompts.note(active.instructions, 'Current workspace');
+      if (action === 'activate') await promptActivateRoom(config, file, prompts, { cwd: process.cwd() });
+      if (action === 'activate_other') await promptActivateRoom(config, file, prompts);
+      if (action === 'deactivate') await promptDeactivateRoom(config, file, prompts, { cwd: process.cwd() });
+    } catch (err) {
+      if (err.message !== 'cancelled') prompts.note(err.message || String(err), 'Workspace action failed');
+    }
+  }
+}
+
+async function runSettingsMenu(config, file, prompts) {
+  while (true) {
+    const action = await prompts.select({
+      message: 'Settings',
+      options: [
+        { value: 'doctor', label: 'System check / install BGE model' },
+        { value: 'account', label: 'Account and config status' },
+        { value: 'mcp', label: 'Show MCP config' },
+        { value: 'sessions', label: 'Manage sessions' },
+        { value: 'server', label: 'Set server URL' },
+        { value: 'back', label: 'Back' },
+      ],
+    });
+    if (prompts.isCancel(action) || action === 'back') return;
+    try {
+      if (action === 'doctor') await promptSystemCheck(config, file, prompts);
+      if (action === 'account') await promptAccountStatus(config, file, prompts);
+      if (action === 'mcp') await promptMcpConfig(config, file, prompts);
+      if (action === 'sessions') await promptManageSessions(config, prompts);
+      if (action === 'server') await promptSetServerUrl(config, file, prompts);
+    } catch (err) {
+      if (err.message !== 'cancelled') prompts.note(err.message || String(err), 'Settings action failed');
+    }
+  }
+}
+
+async function runMainMenu(config, file, opts = {}) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('interactive menu requires a TTY');
+  }
+  if (!isConfigured(config)) {
+    return runSetupWizard(config, file, opts);
+  }
+  const prompts = await loadPrompts();
+  prompts.intro(`SuperCollab ${VERSION}`);
+  try {
+    while (true) {
+      const active = await activeStatus(config, file, {});
+      const action = await prompts.select({
+        message: `Main menu (${config.username || 'user'} - ${active.active ? `active ${active.room_id}` : 'workspace off'})`,
+        options: [
+          { value: 'rooms', label: 'Rooms', hint: 'create, join, browse, invite' },
+          { value: 'chat', label: 'Chat', hint: 'send, read, search, sync' },
+          { value: 'workspace', label: 'Workspace activation', hint: 'turn SuperCollab on/off for directories' },
+          { value: 'settings', label: 'Settings', hint: 'doctor, MCP config, sessions, server URL' },
+          { value: 'setup', label: 'Run onboarding again' },
+          { value: 'exit', label: 'Exit' },
+        ],
+      });
+      if (prompts.isCancel(action) || action === 'exit') {
+        prompts.outro('Done.');
+        return { ok: true };
+      }
+      if (action === 'rooms') await runRoomsMenu(config, file, prompts);
+      if (action === 'chat') await runChatMenu(config, file, prompts);
+      if (action === 'workspace') await runWorkspaceMenu(config, file, prompts);
+      if (action === 'settings') await runSettingsMenu(config, file, prompts);
+      if (action === 'setup') return runSetupWizard(config, file, opts);
+    }
+  } catch (err) {
+    prompts.cancel(err.message === 'cancelled' ? 'Menu closed.' : `Menu stopped: ${err.message}`);
+    throw err;
+  }
+}
+
+async function runSetupWizard(config, file, opts = {}) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('interactive setup requires a TTY; run `supercollab doctor --json` for non-interactive diagnostics');
+  }
+  const prompts = await loadPrompts();
+  prompts.intro(`SuperCollab ${VERSION}`);
+  try {
+    const spin = prompts.spinner();
+    spin.start('Checking this machine and installing the local BGE model');
+    const doctor = await runDoctor(config, file, {});
+    if (doctor.ok) {
+      spin.stop(`Local engine ready: ${doctor.local_engine.id}, ${doctor.local_engine.vector_version || 'sqlite-vec'}`);
+    } else {
+      spin.stop('Local engine check needs attention');
+      for (const line of doctor.advice || []) prompts.note(line, 'Fix');
+      const cont = await prompts.confirm({ message: 'Continue setup anyway?', initialValue: false });
+      if (prompts.isCancel(cont) || !cont) throw new Error('cancelled');
+    }
+
+    await runAuthSetup(config, file, prompts);
+    const room = await runRoomSetup(config, file, prompts);
+    const roomId = room?.room_id || null;
+    const activation = await runActivationSetup(config, file, roomId, prompts);
+    const smoke = await runSetupSmoke(config, file, roomId, prompts);
+
+    const client = await prompts.select({
+      message: 'MCP client config',
+      options: [
+        { value: 'codex', label: 'Codex', hint: 'TOML config snippet' },
+        { value: 'claude', label: 'Claude', hint: 'JSON config snippet' },
+        { value: 'manual', label: 'Manual', hint: 'stdio command' },
+        { value: 'skip', label: 'Skip', hint: 'show later with mcp print-config' },
+      ],
+    });
+    if (prompts.isCancel(client)) throw new Error('cancelled');
+
+    config.onboarding = {
+      completed_at: nowIso(),
+      cli_version: VERSION,
+      room_id: roomId,
+      activation_root: activation?.cwd || null,
+      smoke,
+    };
+    saveConfig(config, file);
+
+    if (client !== 'skip') {
+      prompts.note(mcpConfigText(client, file), `${client} MCP config`);
+    }
+    prompts.outro(`Ready. Config saved at ${file}`);
+    return { ok: true, room_id: roomId, activation, smoke, config: file };
+  } catch (err) {
+    prompts.cancel(err.message === 'cancelled' ? 'Setup cancelled.' : `Setup stopped: ${err.message}`);
+    throw err;
+  }
+}
+
 async function main() {
   const { positionals, opts } = parse(process.argv.slice(2));
-  if (opts.help || positionals.length === 0) { printHelp(); return; }
+  if (opts.help) { printHelp(); return; }
   const [cmd, sub] = positionals;
   const file = configPath(opts);
   const config = attachRuntimeConfig(loadConfig(file), file);
   config.serverUrl = opts.server || config.serverUrl || DEFAULT_SERVER;
 
+  if (positionals.length === 0) {
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      return isConfigured(config)
+        ? runMainMenu(config, file, opts)
+        : runSetupWizard(config, file, opts);
+    }
+    printHelp();
+    return;
+  }
+  if (cmd === 'menu') return runMainMenu(config, file, opts);
+  if (cmd === 'setup') return runSetupWizard(config, file, opts);
+  if (cmd === 'doctor') {
+    const data = await runDoctor(config, file, opts);
+    if (opts.json) return console.log(JSON.stringify(data, null, 2));
+    printDoctor(data);
+    return;
+  }
   if (cmd === 'register') return console.log(JSON.stringify(await doRegister(config, file, opts), null, 2));
   if (cmd === 'login') return console.log(JSON.stringify(await doLogin(config, file, opts), null, 2));
   if (cmd === 'whoami') return console.log(JSON.stringify(await api(config, 'GET', '/v1/me'), null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercollab/cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "SuperCollab CLI and MCP bridge for encrypted local-search agent group chat.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@clack/prompts": "0.11.0",
     "@huggingface/transformers": "3.8.1",
     "better-sqlite3": "12.11.1",
     "sqlite-vec": "0.1.9"