vectorforce 0.0.0-stage → 0.1.0

package/bin/vf.js

@@ -0,0 +1,756 @@
+#!/usr/bin/env node
+
+import { homedir } from 'node:os';
+import { resolve, join, dirname } from 'node:path';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  SqliteStore,
+  ProjectService,
+  CheckpointService,
+  BriefingService,
+  HandoffService,
+  ReasoningService,
+  LlmProvider,
+  CodeIndexProvider,
+  resolveLlmConfig,
+  McpServer,
+  HarnessConfig,
+  createStudioServer,
+  VectorForceError
+} from '../src/index.js';
+
+function getScriptWorkspace() {
+  try {
+    const scriptDir = dirname(resolve(process.argv[1] || ''));
+    let curr = scriptDir;
+    while (curr && curr !== '/' && curr !== homedir()) {
+      if (existsSync(join(curr, '.vectorforce', 'vectorforce.db')) || existsSync(join(curr, '.git'))) {
+        return curr;
+      }
+      const parent = dirname(curr);
+      if (parent === curr) break;
+      curr = parent;
+    }
+  } catch {}
+  return null;
+}
+
+function getWorkspacePath(startDir = process.cwd()) {
+  if (process.env.VF_WORKSPACE) return resolve(process.env.VF_WORKSPACE);
+
+  // If startDir is root or homedir, check if the script location belongs to a VectorForce workspace first
+  if (startDir === '/' || startDir === homedir()) {
+    const scriptWs = getScriptWorkspace();
+    if (scriptWs) return scriptWs;
+  }
+
+  let curr = resolve(startDir);
+  while (true) {
+    // homedir can contain ~/.vectorforce as a global fallback directory; do not treat homedir as a project workspace unless it is a git repo
+    if (curr !== homedir() && curr !== '/') {
+      if (existsSync(join(curr, '.vectorforce')) || existsSync(join(curr, '.git'))) {
+        return curr;
+      }
+    } else if (existsSync(join(curr, '.git'))) {
+      return curr;
+    }
+    const parent = dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+
+  return resolve(startDir);
+}
+
+function getDbPath(startDir = process.cwd()) {
+  if (process.env.VF_DB_PATH) return process.env.VF_DB_PATH;
+
+  // If startDir is root or homedir, check if the script location belongs to a VectorForce workspace first
+  if (startDir === '/' || startDir === homedir()) {
+    const scriptWs = getScriptWorkspace();
+    if (scriptWs) {
+      const dbCandidate = join(scriptWs, '.vectorforce', 'vectorforce.db');
+      if (existsSync(dbCandidate)) return dbCandidate;
+    }
+  }
+
+  // 1. Search up from current directory to root: look for .vectorforce/vectorforce.db or .git
+  let curr = resolve(startDir);
+  while (true) {
+    if (curr !== homedir() && curr !== '/') {
+      const localDb = join(curr, '.vectorforce', 'vectorforce.db');
+      if (existsSync(localDb)) {
+        return localDb;
+      }
+      const localDir = join(curr, '.vectorforce');
+      if (existsSync(localDir)) {
+        return localDb;
+      }
+    }
+    if (existsSync(join(curr, '.git'))) {
+      const gitLocalDir = join(curr, '.vectorforce');
+      mkdirSync(gitLocalDir, { recursive: true, mode: 0o700 });
+      return join(gitLocalDir, 'vectorforce.db');
+    }
+    const parent = dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+
+  // 2. Global fallback in ~/.vectorforce/vectorforce.db
+  try {
+    const homeDir = join(homedir(), '.vectorforce');
+    mkdirSync(homeDir, { recursive: true, mode: 0o700 });
+    return join(homeDir, 'vectorforce.db');
+  } catch {
+    const fallbackDir = join(startDir, '.vectorforce');
+    mkdirSync(fallbackDir, { recursive: true, mode: 0o700 });
+    return join(fallbackDir, 'vectorforce.db');
+  }
+}
+
+function createLlmProvider(workspacePath) {
+  try {
+    return { provider: new LlmProvider(resolveLlmConfig(process.env, {}, workspacePath)), error: null };
+  } catch (err) {
+    return { provider: null, error: err.message };
+  }
+}
+
+function getServices(explicitDbPath, workspacePath) {
+  const cwd = workspacePath || getWorkspacePath(process.cwd());
+  const dbPath = explicitDbPath || getDbPath(cwd);
+  const store = new SqliteStore(dbPath);
+  const projectService = new ProjectService(store);
+  const checkpointService = new CheckpointService(store, projectService);
+  const briefingService = new BriefingService(store, projectService);
+  const handoffService = new HandoffService(store, projectService, checkpointService);
+  const llm = createLlmProvider(cwd);
+  const reasoningService = new ReasoningService(store, projectService, briefingService, {
+    llmProvider: llm.provider,
+    codeIndexProvider: CodeIndexProvider
+  });
+  return {
+    store,
+    projectService,
+    checkpointService,
+    briefingService,
+    handoffService,
+    reasoningService,
+    llmProviderError: llm.error
+  };
+}
+
+function printUsage() {
+  console.log(`
+VectorForce (vf) - Git for AI Engineering Context
+
+Usage:
+  vf init [project_name]                     Initialize current workspace
+  vf task <id> [title]                       Create or register a task
+  vf tasks [active|completed|all]            List tasks in workspace
+  vf policy list                             List allowed document paths
+  vf policy add <relative_path>              Allow document for checkpointing
+  vf checkpoint [options]                    Capture an immutable checkpoint
+  vf resume [options]                        Generate authorized resume briefing
+  vf reason [options]                        AI reasoning over memory + codebase (alias: continue)
+  vf drift [options]                         Check for workspace and document drift
+  vf export [options]                        Export selective handoff package
+  vf import <package_path> [options]         Import handoff package into workspace
+  vf recap [options]                         Show weekly timeline & engineering recap
+  vf timeline [options]                      Alias for vf recap
+  vf studio [options]                        Launch VectorForce Studio web control center
+  vf ui [options]                            Alias for vf studio
+  vf mcp                                     Start stdio MCP server for Antigravity / Command Code
+  vf config                                  Display MCP configuration snippet for harnesses
+  vf help                                    Show this help
+
+Checkpoint options:
+  --task <id>          Task identifier
+  --summary <text>     Concise summary
+  --goal <text>        Add a goal (can repeat)
+  --constraint <text>  Add a constraint (can repeat)
+  --decision <text>    Add decision format "ID:Title:Rationale" (can repeat)
+  --next <text>        Add next step (can repeat)
+  --doc <path>         Request allowlisted document (can repeat)
+  --no-git             Skip Git status collection
+
+Resume options:
+  --task <id>          Task identifier
+  --checkpoint <id>    Specific checkpoint ID (defaults to latest head)
+  --dest <harness>     Destination harness: antigravity, command-code, muse, codex, pi, cli
+
+Reason options:
+  --task <id>          Task identifier
+  --checkpoint <id>    Specific checkpoint ID (defaults to latest head)
+  --focus <text>       Optional question or focus for the reasoning pass
+  --model <name>       Override the model id (e.g. a Meta Llama or Muse model)
+  --no-code            Reason over memory only (do not send code context)
+  --raw                Print the deterministic briefing without calling the model
+  --dest <harness>     Destination harness: antigravity, command-code, muse, codex, pi, cli
+
+Recap / Timeline options:
+  --days <number>      Number of days to include (default: 7)
+  --task <id>          Filter by specific task
+  --dest <harness>     Destination harness: antigravity, command-code, muse, codex, pi, cli
+
+Handoff options:
+  --task <id>          Task identifier
+  --recipient <name>   Target recipient/audience
+  --checkpoint <id>    Specific checkpoint ID (defaults to latest head)
+  --dest <harness>     Destination harness: antigravity, command-code, muse, codex, pi, cli, any
+  --preview            Preview export bundle without writing file
+  --out <path>         Target output path for handoff package
+`);
+}
+
+function parseFlags(args) {
+  const flags = {
+    goals: [],
+    constraints: [],
+    decisions: [],
+    nextSteps: [],
+    docs: [],
+    includeGit: true
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--task' && args[i + 1]) {
+      flags.task = args[++i];
+    } else if (arg === '--summary' && args[i + 1]) {
+      flags.summary = args[++i];
+    } else if (arg === '--checkpoint' && args[i + 1]) {
+      flags.checkpoint = args[++i];
+    } else if (arg === '--dest' && args[i + 1]) {
+      flags.dest = args[++i];
+    } else if (arg === '--goal' && args[i + 1]) {
+      flags.goals.push(args[++i]);
+    } else if (arg === '--constraint' && args[i + 1]) {
+      flags.constraints.push(args[++i]);
+    } else if (arg === '--decision' && args[i + 1]) {
+      const parts = args[++i].split(':');
+      flags.decisions.push({
+        id: parts[0] || 'DEC',
+        title: parts[1] || parts[0],
+        rationale: parts[2] || 'Approved architecture decision'
+      });
+    } else if (arg === '--next' && args[i + 1]) {
+      flags.nextSteps.push(args[++i]);
+    } else if (arg === '--doc' && args[i + 1]) {
+      flags.docs.push(args[++i]);
+    } else if (arg === '--model' && args[i + 1]) {
+      flags.model = args[++i];
+    } else if (arg === '--focus' && args[i + 1]) {
+      flags.focus = args[++i];
+    } else if (arg === '--no-code') {
+      flags.includeCode = false;
+    } else if (arg === '--raw') {
+      flags.raw = true;
+    } else if (arg === '--no-git') {
+      flags.includeGit = false;
+    } else if (arg === '--recipient' && args[i + 1]) {
+      flags.recipient = args[++i];
+    } else if (arg === '--preview') {
+      flags.preview = true;
+    } else if (arg === '--out' && args[i + 1]) {
+      flags.outPath = args[++i];
+    } else if (arg === '--port' && args[i + 1]) {
+      flags.port = parseInt(args[++i], 10);
+    } else if (arg === '--workspace' && args[i + 1]) {
+      flags.workspace = resolve(args[++i]);
+    } else if (arg === '--db' && args[i + 1]) {
+      flags.db = resolve(args[++i]);
+    }
+  }
+  return flags;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const flags = parseFlags(args.slice(1));
+  const cwd = flags.workspace || getWorkspacePath(process.cwd());
+  const dbPath = flags.db || getDbPath(cwd);
+  const { store, projectService, checkpointService, briefingService, handoffService, reasoningService, llmProviderError } = getServices(dbPath, cwd);
+
+  try {
+    switch (command) {
+      case 'init': {
+        const name = args[1] || null;
+        const project = projectService.initProject(cwd, name);
+        console.log(`Initialized VectorForce project: ${project.name} (${project.project_id})`);
+        break;
+      }
+
+      case 'task': {
+        const sub = args[1];
+        if (sub === 'complete' || sub === 'done') {
+          const taskId = args[2];
+          if (!taskId) {
+            console.error('Error: task id required (e.g. vf task complete phase-5-pilot)');
+            process.exit(1);
+          }
+          const task = projectService.updateTaskStatus(cwd, taskId, 'completed');
+          console.log(`Task marked as completed: ${task.title} (${task.task_id}) [${task.status}]`);
+          break;
+        }
+        const taskId = sub;
+        if (!taskId) {
+          console.error('Error: task id required (e.g. vf task feat-sqlite "Implement SQLite store")');
+          process.exit(1);
+        }
+        const title = args.slice(2).join(' ') || taskId;
+        const task = projectService.createTask(cwd, taskId, title);
+        console.log(`Task registered: ${task.title} (${task.task_id}) [${task.status}]`);
+        break;
+      }
+
+      case 'tasks': {
+        const filter = args[1] || 'active';
+        const project = projectService.getProjectForWorkspace(cwd);
+        const tasks = store.listTasks(project.project_id, filter);
+        console.log(`Tasks for ${project.name} [${filter}]:`);
+        for (const t of tasks) {
+          console.log(`- [${t.status}] ${t.task_id}: ${t.title}`);
+        }
+        break;
+      }
+
+      case 'policy': {
+        const sub = args[1];
+        const project = projectService.getProjectForWorkspace(cwd);
+        if (sub === 'list') {
+          const list = store.getDocumentPolicy(project.project_id);
+          console.log(`Document allowlist for ${project.name}:`);
+          if (list.length === 0) console.log('  (no documents allowlisted)');
+          for (const p of list) console.log(`  - ${p}`);
+        } else if (sub === 'add') {
+          const docPath = args[2];
+          if (!docPath) {
+            console.error('Error: relative document path required');
+            process.exit(1);
+          }
+          const current = store.getDocumentPolicy(project.project_id);
+          const updated = store.setDocumentPolicy(project.project_id, [...current, docPath]);
+          console.log(`Updated allowlist: ${updated.join(', ')}`);
+        } else {
+          console.error('Unknown policy subcommand. Use "vf policy list" or "vf policy add <path>"');
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'checkpoint': {
+        const flags = parseFlags(args.slice(1));
+        if (!flags.summary) {
+          console.error('Error: --summary <text> is required');
+          process.exit(1);
+        }
+        const receipt = checkpointService.captureCheckpoint({
+          workspacePath: cwd,
+          taskId: flags.task,
+          summary: flags.summary,
+          goals: flags.goals,
+          constraints: flags.constraints,
+          decisions: flags.decisions,
+          nextSteps: flags.nextSteps,
+          requestedDocuments: flags.docs,
+          includeGit: flags.includeGit,
+          authorName: process.env.USER || 'developer',
+          authorHarness: 'cli'
+        });
+        console.log(`Checkpoint saved: ${receipt.reference_id} [${receipt.status}]`);
+        if (receipt.warnings.length > 0) {
+          for (const w of receipt.warnings) console.warn(`Warning: ${w}`);
+        }
+        break;
+      }
+
+      case 'resume': {
+        const flags = parseFlags(args.slice(1));
+        const result = briefingService.generateBriefing({
+          workspacePath: cwd,
+          taskId: flags.task,
+          checkpointId: flags.checkpoint,
+          destination: flags.dest || 'cli'
+        });
+        console.log(result.briefingText);
+        break;
+      }
+
+      case 'drift': {
+        const flags = parseFlags(args.slice(1));
+        const result = briefingService.generateBriefing({
+          workspacePath: cwd,
+          taskId: flags.task,
+          checkpointId: flags.checkpoint,
+          destination: 'cli'
+        });
+        if (result.driftDetected) {
+          console.log('⚠️ DRIFT DETECTED:');
+          for (const w of result.warnings) console.log(`- ${w}`);
+        } else {
+          console.log('✔ No drift detected: workspace and document state match recorded checkpoint.');
+        }
+        break;
+      }
+
+      case 'reason':
+      case 'continue': {
+        const flags = parseFlags(args.slice(1));
+        if (flags.raw) {
+          const raw = briefingService.generateBriefing({
+            workspacePath: cwd,
+            taskId: flags.task,
+            checkpointId: flags.checkpoint,
+            destination: flags.dest || 'cli'
+          });
+          console.log(raw.briefingText);
+          break;
+        }
+        if (llmProviderError) {
+          console.warn(`Warning: LLM configuration issue: ${llmProviderError}`);
+        }
+        const result = await reasoningService.reasonAboutTask({
+          workspacePath: cwd,
+          taskId: flags.task,
+          checkpointId: flags.checkpoint,
+          destination: flags.dest || 'cli',
+          focus: flags.focus,
+          model: flags.model,
+          maxTokens: flags.maxTokens ? parseInt(flags.maxTokens, 10) : 4000,
+          includeCode: flags.includeCode !== false
+        });
+        console.log(result.narrativeText);
+        if (result.degraded) {
+          console.error(`\n⚠ AI reasoning unavailable${result.error ? ` (${result.error})` : ''} — showing deterministic briefing.`);
+        } else {
+          console.error(`\n— reasoned by ${result.provider}/${result.model} · ${result.codeFilesConsidered} code file(s) considered`);
+        }
+        break;
+      }
+
+      case 'export':
+      case 'export-handoff': {
+        const flags = parseFlags(args.slice(1));
+        if (!flags.task) {
+          console.error('Error: --task <id> is required for handoff export.');
+          process.exit(1);
+        }
+        if (!flags.recipient) {
+          console.error('Error: --recipient <name> is required for handoff export.');
+          process.exit(1);
+        }
+        const result = handoffService.exportHandoff({
+          workspacePath: cwd,
+          taskId: flags.task,
+          checkpointId: flags.checkpoint,
+          recipient: flags.recipient,
+          destinationHarness: flags.dest || 'any',
+          preview: flags.preview === true,
+          outPath: flags.outPath
+        });
+        if (result.preview) {
+          console.log(`\n✔ Handoff Preview for [${flags.task}] to ${flags.recipient}:`);
+          console.log(JSON.stringify(result.handoff, null, 2));
+        } else {
+          console.log(`\n✔ Handoff exported successfully: ${result.package_id}`);
+          console.log(`  Bundle Path: ${result.bundlePath}`);
+          console.log(`  Receipt:     ${result.receipt.operation_id} [${result.receipt.status}]`);
+        }
+        break;
+      }
+
+      case 'import':
+      case 'import-handoff': {
+        const bundlePath = args[1];
+        if (!bundlePath || bundlePath.startsWith('--')) {
+          console.error('Error: Package path required: vf import <package_path> [--task <id>]');
+          process.exit(1);
+        }
+        const flags = parseFlags(args.slice(2));
+        const result = handoffService.importHandoff({
+          workspacePath: cwd,
+          bundlePath,
+          targetTaskId: flags.task
+        });
+        console.log(`\n✔ Handoff imported successfully into task [${result.task.task_id}]`);
+        console.log(`  Imported Checkpoint: ${result.importedCheckpointId}`);
+        console.log(`  Receipt:             ${result.receipt.operation_id} [${result.receipt.status}]`);
+        break;
+      }
+
+      case 'mcp': {
+        const server = new McpServer({ store, projectService, checkpointService, briefingService, handoffService, reasoningService }, cwd);
+        server.connect(process.stdin, process.stdout);
+        process.on('SIGINT', () => {
+          store.close();
+          process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+          store.close();
+          process.exit(0);
+        });
+        // Keep process alive for stdio stream; do not execute finally store.close()
+        return;
+      }
+
+      case 'config': {
+        const sub = args[1];
+        if (sub === 'install' || sub === 'setup') {
+          const target = (args[2] || 'all').toLowerCase();
+          const installed = [];
+          if (target === 'antigravity' || target === 'all') {
+            const p = HarnessConfig.installAntigravity(cwd);
+            installed.push(`Antigravity -> ${p}`);
+          }
+          if (target === 'command-code' || target === 'cmd' || target === 'all') {
+            const p = HarnessConfig.installCommandCode(cwd);
+            installed.push(`Command Code -> ${p}`);
+          }
+          if (target === 'muse' || target === 'muse-code' || target === 'all') {
+            const p = HarnessConfig.installMuseCode(cwd);
+            installed.push(`Muse Code -> ${p}`);
+          }
+          if (target === 'codex' || target === 'all') {
+            const p = HarnessConfig.installCodex(cwd);
+            installed.push(`Codex -> ${p}`);
+          }
+          console.log(`\n✔ Configured harness integration(s):\n  - ${installed.join('\n  - ')}`);
+          break;
+        }
+
+        if (sub === 'uninstall' || sub === 'remove') {
+          const target = (args[2] || 'all').toLowerCase();
+          const uninstalled = [];
+          if (target === 'antigravity' || target === 'all') {
+            if (HarnessConfig.uninstallAntigravity(cwd)) uninstalled.push('Antigravity');
+          }
+          if (target === 'command-code' || target === 'cmd' || target === 'all') {
+            if (HarnessConfig.uninstallCommandCode(cwd)) uninstalled.push('Command Code');
+          }
+          if (target === 'muse' || target === 'muse-code' || target === 'all') {
+            if (HarnessConfig.uninstallMuseCode(cwd)) uninstalled.push('Muse Code');
+          }
+          if (target === 'codex' || target === 'all') {
+            if (HarnessConfig.uninstallCodex(cwd)) uninstalled.push('Codex');
+          }
+          console.log(`\n✔ Removed harness integration(s): ${uninstalled.length ? uninstalled.join(', ') : 'none found'}`);
+          break;
+        }
+
+        if (sub === 'set') {
+          const key = args[2];
+          const val = args[3];
+          if (!key || val === undefined) {
+            console.error('Usage: node bin/vf.js config set <KEY> <VALUE>');
+            process.exit(1);
+          }
+          const vfDir = join(cwd, '.vectorforce');
+          mkdirSync(vfDir, { recursive: true, mode: 0o700 });
+          const cfgPath = join(vfDir, 'config.json');
+          let existing = {};
+          if (existsSync(cfgPath)) {
+            try { existing = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch {}
+          }
+          existing[key] = val;
+          writeFileSync(cfgPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+          console.log(`\n✔ Saved configuration [${key}] in ${cfgPath}`);
+          break;
+        }
+
+        if (sub === 'openrouter') {
+          const key = args[2];
+          const model = args[3] || 'deepseek/deepseek-v4.1-flash-1017';
+          if (!key) {
+            console.error('Usage: node bin/vf.js config openrouter <API_KEY> [MODEL]');
+            process.exit(1);
+          }
+          const vfDir = join(cwd, '.vectorforce');
+          mkdirSync(vfDir, { recursive: true, mode: 0o700 });
+          const cfgPath = join(vfDir, 'config.json');
+          let existing = {};
+          if (existsSync(cfgPath)) {
+            try { existing = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch {}
+          }
+          existing.VF_LLM_PROVIDER = 'openrouter';
+          existing.OPENROUTER_API_KEY = key;
+          existing.VF_OPENROUTER_MODEL = model;
+          writeFileSync(cfgPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+          console.log(`\n✔ Configured OpenRouter in ${cfgPath}`);
+          console.log(`  Provider: openrouter`);
+          console.log(`  Model:    ${model}`);
+          console.log(`  Base URL: https://openrouter.ai/api/v1`);
+          break;
+        }
+
+        if (sub === 'muse') {
+          const key = args[2];
+          const model = args[3] || 'muse-spark-1.3';
+          if (!key) {
+            console.error('Usage: node bin/vf.js config muse <API_KEY> [MODEL]');
+            process.exit(1);
+          }
+          const vfDir = join(cwd, '.vectorforce');
+          mkdirSync(vfDir, { recursive: true, mode: 0o700 });
+          const cfgPath = join(vfDir, 'config.json');
+          let existing = {};
+          if (existsSync(cfgPath)) {
+            try { existing = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch {}
+          }
+          existing.VF_LLM_PROVIDER = 'muse';
+          existing.MODEL_API_KEY = key;
+          existing.VF_MUSE_MODEL = model;
+          writeFileSync(cfgPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+          console.log(`\n✔ Configured Muse in ${cfgPath}`);
+          console.log(`  Provider: muse`);
+          console.log(`  Model:    ${model}`);
+          console.log(`  Base URL: https://api.meta.ai/v1`);
+          break;
+        }
+
+        if (sub === 'show' || sub === 'status') {
+          const cfg = resolveLlmConfig(process.env, {}, cwd);
+          console.log('\nVectorForce AI Reasoning Configuration:');
+          console.log(`  Provider: ${cfg.provider}`);
+          console.log(`  Model:    ${cfg.model}`);
+          console.log(`  Base URL: ${cfg.baseUrl}`);
+          console.log(`  API Key:  ${cfg.apiKey ? 'configured (hidden)' : 'none (falling back to local)'}`);
+          break;
+        }
+
+        const binPath = resolve(process.argv[1]);
+        console.log(`
+VectorForce Harness Configuration:
+
+1. Google Antigravity Configuration:
+   File: .agents/mcp_config.json (or ~/.gemini/config/mcp_config.json)
+   Content:
+   {
+     "mcpServers": {
+       "vectorforce": {
+         "command": "node",
+         "args": ["${binPath}", "mcp"]
+       }
+     }
+   }
+
+2. Meta Muse Code (muse-code) Configuration:
+   File: .muse/mcp_config.json (or musecode.json)
+   Content:
+   {
+     "mcpServers": {
+       "vectorforce": {
+         "command": "node",
+         "args": ["${binPath}", "mcp"],
+         "env": { "VF_HARNESS": "muse-code" }
+       }
+     }
+   }
+
+3. Command Code (command-code) Configuration:
+   Run command:
+   cmd mcp add --transport stdio vectorforce -- node ${binPath} mcp
+
+4. OpenAI Codex (codex) Configuration:
+   File: .codex/config.toml (or codex.json)
+   Content:
+   [mcp_servers.vectorforce]
+   command = "node"
+   args = ["${binPath}", "mcp"]
+   [mcp_servers.vectorforce.env]
+   VF_HARNESS = "codex"
+
+   Or run command:
+   codex mcp add vectorforce -- node ${binPath} mcp
+
+   Automated Setup:
+   node bin/vf.js config install codex
+   node bin/vf.js config install all
+
+5. AI Reasoning (vf reason / reason_about_task):
+   Local Ollama (default, 100% private):
+     VF_LLM_PROVIDER=ollama
+     VF_OLLAMA_BASE_URL=http://127.0.0.1:11434
+     VF_OLLAMA_MODEL=llama3.1:8b
+
+   Cloud Meta Muse (Responses API):
+     VF_LLM_PROVIDER=muse
+     MODEL_API_KEY=<your-key>
+     VF_MUSE_MODEL=muse-spark-1.3  # default
+     VF_MUSE_BASE_URL=https://api.meta.ai/v1  # default
+     # Or: node bin/vf.js config muse <API_KEY> [MODEL]
+
+   Cloud OpenAI Codex / GPT:
+     VF_LLM_PROVIDER=codex
+     VF_CODEX_BASE_URL=https://api.openai.com/v1
+     VF_CODEX_API_KEY=<your-key>
+     VF_CODEX_MODEL=o3-mini
+
+   Cloud OpenRouter (DeepSeek v4.1 Flash / Multi-Model):
+     VF_LLM_PROVIDER=openrouter
+     OPENROUTER_API_KEY=<your-key>  # or VF_OPENROUTER_API_KEY
+     VF_OPENROUTER_MODEL=deepseek/deepseek-v4.1-flash-1017  # default
+
+   Privacy: set VF_LLM_ALLOW_CODE=false (or run with --no-code) to keep source out of the prompt.
+`);
+        break;
+      }
+
+      case 'studio':
+      case 'ui': {
+        const flags = parseFlags(args.slice(1));
+        const port = flags.port || 3210;
+        const studio = createStudioServer({
+          dbPath: getDbPath(),
+          workspacePath: cwd,
+          port
+        });
+        const url = await studio.start();
+        console.log(`\n🚀 VectorForce Studio is running at: ${url}`);
+        console.log(`   Connected to SQLite: ${getDbPath()}`);
+        console.log(`   Interactive Topology & AI Memory: ${url}`);
+        console.log(`   Press Ctrl+C to stop.\n`);
+
+        try {
+          const { exec } = await import('node:child_process');
+          exec(`open ${url}`);
+        } catch {}
+
+        process.on('SIGINT', async () => {
+          await studio.stop();
+          process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+          await studio.stop();
+          process.exit(0);
+        });
+        return;
+      }
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        printUsage();
+        process.exit(1);
+    }
+  } catch (err) {
+    if (err instanceof VectorForceError) {
+      console.error(`VectorForce Error [${err.code}]: ${err.message}`);
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exit(1);
+  } finally {
+    if (command !== 'mcp' && command !== 'studio' && command !== 'ui') {
+      store.close();
+    }
+  }
+}
+
+main();