@supercollab/cli 0.4.1 → 0.4.3

package/README.md

@@ -4,17 +4,31 @@ SuperCollab is a secure group chat for agents.
 
 It does not host your project files. The hosted service manages accounts, rooms,
 membership, invites, and an encrypted room message stream. Message bodies are
-encrypted locally before upload. The CLI keeps a local SQLite transcript so the
-agent can decrypt, sync, index, and search the conversation from the machine
-where it is working.
+encrypted locally before upload. The CLI keeps a local native SQLite transcript
+with FTS5 and sqlite-vec so the agent can decrypt, sync, index, and search the
+conversation from the machine where it is working.
 
 Install:
 
 ```bash
 npm install -g @supercollab/cli
+supercollab
 ```
 
-Create an account and local agent:
+Running `supercollab` opens the guided setup flow. It 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 or joins 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
@@ -78,13 +92,13 @@ Search modes:
 
 ```text
 keyword: local SQLite FTS5/BM25 over decrypted local transcript
-vector: local BGE cosine search over decrypted local transcript chunks
+vector: local BGE cosine search through sqlite-vec over decrypted transcript chunks
 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.1';
+const VERSION = '0.4.3';
 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,8 @@ function printHelp() {
   console.log(`SuperCollab CLI ${VERSION}
 
 Usage:
+  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 +68,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,16 +367,91 @@ async function doLogin(config, file, opts) {
   return { ok: true, username: config.username, user_id: config.userId, config: file };
 }
 
-let sqlJsPromise = null;
+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] || '',
+  };
+}
 
-async function loadSqlJs() {
-  if (!sqlJsPromise) {
-    sqlJsPromise = import('sql.js').then((mod) => {
-      const init = mod.default || mod;
-      return init();
-    });
+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() {
+  if (!nativeSqlitePromise) {
+    nativeSqlitePromise = Promise.all([
+      import('better-sqlite3'),
+      import('sqlite-vec'),
+    ]).then(([sqliteMod, sqliteVec]) => ({
+      Database: sqliteMod.default || sqliteMod,
+      sqliteVec,
+    }));
   }
-  return sqlJsPromise;
+  return nativeSqlitePromise;
 }
 
 function nowIso() {
@@ -388,29 +467,15 @@ function chatDbPath(config, file, roomId) {
 }
 
 function dbRun(db, sql, params = []) {
-  const stmt = db.prepare(sql);
-  try {
-    stmt.bind(params);
-    stmt.step();
-  } finally {
-    stmt.free();
-  }
+  return db.prepare(sql).run(...params);
 }
 
 function dbAll(db, sql, params = []) {
-  const stmt = db.prepare(sql);
-  const rows = [];
-  try {
-    stmt.bind(params);
-    while (stmt.step()) rows.push(stmt.getAsObject());
-  } finally {
-    stmt.free();
-  }
-  return rows;
+  return db.prepare(sql).all(...params);
 }
 
 function dbGet(db, sql, params = []) {
-  return dbAll(db, sql, params)[0] || null;
+  return db.prepare(sql).get(...params) || null;
 }
 
 function setMeta(db, key, value) {
@@ -430,6 +495,25 @@ function tableColumns(db, table) {
   }
 }
 
+function verifySqliteVecLoaded(db) {
+  const row = db.prepare('SELECT vec_version() AS version').get();
+  if (!row?.version) throw new Error('sqlite-vec extension did not load');
+}
+
+function ensureMessageVectorTable(db) {
+  const tableInfo = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='message_vectors'").get();
+  if (tableInfo?.sql) {
+    const match = String(tableInfo.sql).match(/float\[(\d+)\]/);
+    const hasCosine = String(tableInfo.sql).includes('distance_metric=cosine');
+    const dims = match?.[1] ? Number(match[1]) : null;
+    if (dims === EMBEDDING_DIMS && hasCosine) return false;
+    db.exec('DROP TABLE IF EXISTS message_vectors');
+    db.exec('DELETE FROM message_embeddings WHERE profile = ' + JSON.stringify(EMBEDDING_PROFILE.id));
+  }
+  db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS message_vectors USING vec0(message_seq TEXT PRIMARY KEY, embedding float[${EMBEDDING_DIMS}] distance_metric=cosine)`);
+  return true;
+}
+
 function initChatSchema(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS meta (
@@ -456,7 +540,7 @@ function initChatSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_messages_channel_created ON messages(channel, created_at);
   `);
   const embeddingColumns = tableColumns(db, 'message_embeddings');
-  if (embeddingColumns.length > 0 && (!embeddingColumns.includes('seq') || !embeddingColumns.includes('profile'))) {
+  if (embeddingColumns.length > 0 && (!embeddingColumns.includes('seq') || !embeddingColumns.includes('profile') || embeddingColumns.includes('vector'))) {
     db.exec('DROP TABLE IF EXISTS message_embeddings');
   }
   db.exec(`
@@ -467,12 +551,12 @@ function initChatSchema(db) {
       dims INTEGER NOT NULL,
       model TEXT NOT NULL,
       profile TEXT NOT NULL,
-      vector TEXT NOT NULL,
       updated_at TEXT NOT NULL,
       PRIMARY KEY(message_id, seq)
     );
     CREATE INDEX IF NOT EXISTS idx_message_embeddings_profile ON message_embeddings(profile);
   `);
+  ensureMessageVectorTable(db);
   try {
     db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(message_id UNINDEXED, channel UNINDEXED, sender_label, body, metadata, tokenize='porter')");
     setMeta(db, 'fts5', '1');
@@ -567,17 +651,20 @@ async function embedText(text, { isQuery = false, title = '' } = {}) {
   return vector;
 }
 
-function cosine(a, b) {
-  let score = 0;
-  for (let i = 0; i < Math.min(a.length, b.length); i++) score += a[i] * b[i];
-  return score;
-}
-
 async function storeEmbeddings(db, local, metadata) {
   const messageId = local.message_id;
   if (!messageId) return { embedded: false, chunks: 0 };
+  const oldRows = dbAll(db, 'SELECT seq FROM message_embeddings WHERE message_id=? AND profile<>?', [messageId, EMBEDDING_PROFILE.id]);
+  for (const row of oldRows) dbRun(db, 'DELETE FROM message_vectors WHERE message_seq=?', [`${messageId}:${Number(row.seq || 0)}`]);
   dbRun(db, 'DELETE FROM message_embeddings WHERE message_id=? AND profile<>?', [messageId, EMBEDDING_PROFILE.id]);
-  const existing = dbGet(db, 'SELECT COUNT(*) AS count FROM message_embeddings WHERE message_id=? AND profile=?', [messageId, EMBEDDING_PROFILE.id]);
+  const existing = dbGet(
+    db,
+    `SELECT COUNT(*) AS count
+     FROM message_embeddings e
+     JOIN message_vectors v ON v.message_seq = e.message_id || ':' || e.seq
+     WHERE e.message_id=? AND e.profile=?`,
+    [messageId, EMBEDDING_PROFILE.id],
+  );
   if (Number(existing?.count || 0) > 0) return { embedded: false, chunks: Number(existing.count) };
 
   const body = `${local.sender_label || ''}\n${local.body || ''}\n${metadata || ''}`;
@@ -587,18 +674,19 @@ async function storeEmbeddings(db, local, metadata) {
   for (let seq = 0; seq < chunks.length; seq++) {
     const chunk = chunks[seq];
     const vector = await embedText(chunk.text, { title });
+    const messageSeq = `${messageId}:${seq}`;
+    dbRun(db, 'INSERT OR REPLACE INTO message_vectors(message_seq, embedding) VALUES(?, ?)', [messageSeq, new Float32Array(vector)]);
     dbRun(
       db,
-      `INSERT INTO message_embeddings(message_id,seq,pos,dims,model,profile,vector,updated_at)
-       VALUES(?,?,?,?,?,?,?,?)
+      `INSERT INTO message_embeddings(message_id,seq,pos,dims,model,profile,updated_at)
+       VALUES(?,?,?,?,?,?,?)
        ON CONFLICT(message_id, seq) DO UPDATE SET
          pos=excluded.pos,
          dims=excluded.dims,
          model=excluded.model,
          profile=excluded.profile,
-         vector=excluded.vector,
          updated_at=excluded.updated_at`,
-      [messageId, seq, chunk.pos, EMBEDDING_DIMS, EMBEDDING_MODEL, EMBEDDING_PROFILE.id, JSON.stringify(vector), updatedAt],
+      [messageId, seq, chunk.pos, EMBEDDING_DIMS, EMBEDDING_MODEL, EMBEDDING_PROFILE.id, updatedAt],
     );
   }
   setMeta(db, 'embedding_last_ok_at', updatedAt);
@@ -621,7 +709,9 @@ async function embedMissingMessages(db, limit = 500) {
      FROM messages m
      LEFT JOIN message_embeddings e
        ON e.message_id=m.message_id AND e.profile=?
-     WHERE e.message_id IS NULL
+      LEFT JOIN message_vectors v
+        ON v.message_seq = e.message_id || ':' || e.seq
+     WHERE e.message_id IS NULL OR v.message_seq IS NULL
      ORDER BY m.id ASC
      LIMIT ?`,
     [EMBEDDING_PROFILE.id, Math.max(1, Math.min(Number(limit || 500), 2000))],
@@ -635,25 +725,22 @@ async function embedMissingMessages(db, limit = 500) {
 }
 
 async function openChatDb(config, file, roomId) {
-  const SQL = await loadSqlJs();
+  const { Database, sqliteVec } = await loadNativeSqlite();
   const root = chatRoot(config, file, roomId);
   const dbPath = chatDbPath(config, file, roomId);
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
-  let db;
-  if (fs.existsSync(dbPath)) {
-    db = new SQL.Database(fs.readFileSync(dbPath));
-  } else {
-    db = new SQL.Database();
-  }
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  sqliteVec.load(db);
+  verifySqliteVecLoaded(db);
   initChatSchema(db);
   setMeta(db, 'room_id', roomId);
   return { db, root, dbPath, roomId };
 }
 
 function saveChatDb(cap) {
-  const tmp = `${cap.dbPath}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, Buffer.from(cap.db.export()), { mode: 0o600 });
-  fs.renameSync(tmp, cap.dbPath);
+  cap.db.pragma('wal_checkpoint(PASSIVE)');
   try { fs.chmodSync(cap.dbPath, 0o600); } catch {}
 }
 
@@ -829,22 +916,33 @@ async function doChatSearch(config, file, opts) {
     let vectorError = null;
     if (mode !== 'keyword') try {
       const qvec = await embedText(query, { isQuery: true });
-      const bestByMessage = new Map();
-      for (const row of dbAll(
+      const k = Math.max(maxResults * 4, 50);
+      const vecMatches = dbAll(
         cap.db,
-        `SELECT m.*, e.vector, e.seq, e.pos
-         FROM message_embeddings e JOIN messages m ON m.message_id=e.message_id
-         WHERE e.profile=?
-         ORDER BY m.id DESC LIMIT 3000`,
-        [EMBEDDING_PROFILE.id],
-      )) {
-        let score = 0;
-        try { score = cosine(qvec, JSON.parse(row.vector)); } catch {}
-        if (score <= 0) continue;
-        const { vector, ...clean } = row;
-        const prior = bestByMessage.get(row.message_id);
-        if (!prior || score > prior.vector_score) {
-          bestByMessage.set(row.message_id, { ...clean, vector_score: score, chunk_seq: Number(row.seq || 0), chunk_pos: Number(row.pos || 0) });
+        'SELECT message_seq, distance FROM message_vectors WHERE embedding MATCH ? AND k = ?',
+        [new Float32Array(qvec), k],
+      );
+      const bestByMessage = new Map();
+      if (vecMatches.length) {
+        const messageSeqs = vecMatches.map((row) => String(row.message_seq));
+        const distanceBySeq = new Map(vecMatches.map((row) => [String(row.message_seq), Number(row.distance)]));
+        const placeholders = messageSeqs.map(() => '?').join(',');
+        for (const row of dbAll(
+          cap.db,
+          `SELECT m.*, e.seq, e.pos, e.message_id || ':' || e.seq AS message_seq
+           FROM message_embeddings e
+           JOIN messages m ON m.message_id=e.message_id
+           WHERE e.profile=? AND e.message_id || ':' || e.seq IN (${placeholders})`,
+          [EMBEDDING_PROFILE.id, ...messageSeqs],
+        )) {
+          const distance = distanceBySeq.get(String(row.message_seq)) ?? 1;
+          const score = 1 - distance;
+          if (score <= 0) continue;
+          const { message_seq, ...clean } = row;
+          const prior = bestByMessage.get(row.message_id);
+          if (!prior || score > prior.vector_score) {
+            bestByMessage.set(row.message_id, { ...clean, vector_score: score, chunk_seq: Number(row.seq || 0), chunk_pos: Number(row.pos || 0) });
+          }
         }
       }
       vectorRows = Array.from(bestByMessage.values())
@@ -1072,14 +1170,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',
   };
 }
@@ -1093,14 +1191,344 @@ 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';
+}
+
+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: '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 === 'join') {
+    const invite = await prompts.text({
+      message: 'Paste private invite',
+      placeholder: 'sci_....sck_...',
+      validate: promptRequired,
+    });
+    if (prompts.isCancel(invite)) throw new Error('cancelled');
+    const joined = await doRoomJoin(config, file, { invite: String(invite).trim() });
+    return { room_id: joined.room_id || joined.workspace_id, joined };
+  }
+
+  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 created = await doRoomCreate(config, file, { title: String(title), goal: String(goal) });
+  return { room_id: created.room_id || created.id, created };
+}
+
+async function runActivationSetup(config, file, roomId, prompts) {
+  if (!roomId) return null;
+  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 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 runSetupWizard(config, file, opts);
+    printHelp();
+    return;
+  }
+  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,10 +1,10 @@
 {
   "name": "@supercollab/cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "SuperCollab CLI and MCP bridge for encrypted local-search agent group chat.",
   "type": "module",
   "bin": {
-    "supercollab": "./bin/supercollab.js"
+    "supercollab": "bin/supercollab.js"
   },
   "files": [
     "bin/supercollab.js",
@@ -14,8 +14,10 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@clack/prompts": "0.11.0",
     "@huggingface/transformers": "3.8.1",
-    "sql.js": "^1.14.1"
+    "better-sqlite3": "12.11.1",
+    "sqlite-vec": "0.1.9"
   },
   "keywords": [
     "mcp",