total-recall-brain 3.1.0

package/src/cli/connect.mjs

@@ -0,0 +1,872 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agentDir as configAgentDir, brainDir as configBrainDir, xdgConfigHome, trBrain, trPat } from '../core/config.mjs';
+import { fileURLToPath } from 'node:url';
+import { resolveAgentDir, getBothBrains, detectProjectBrain } from './agent-dir.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Resolve templates dir relative to this file (src/cli/ → ../../templates/)
+const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates');
+
+const CLIENTS = {
+  vscode: {
+    label: 'VS Code Copilot',
+    mode: 'file',
+    target: path.join('.github', 'copilot-instructions.md'),
+    render: instructions => `<!-- Total Recall — auto-generated by \`npx total-recall connect vscode\` -->\n<!-- Do not edit; re-run connect to refresh -->\n\n${instructions}`
+  },
+  pi: {
+    label: 'Pi Coding Agent',
+    mode: 'global-symlink',
+    globalTarget: path.join(os.homedir(), '.pi', 'agent', 'AGENTS.md'),
+    localTarget: 'AGENTS.md',
+  },
+  hermes: {
+    label: 'Hermes Agent',
+    mode: 'hermes',
+    memoryPath: path.join(os.homedir(), '.hermes', 'memories', 'MEMORY.md'),
+    userPath:   path.join(os.homedir(), '.hermes', 'memories', 'USER.md'),
+  },
+  openclaw: {
+    label: 'OpenClaw',
+    mode: 'openclaw',
+    memoryTarget: 'MEMORY.md',
+    agentsTarget: 'AGENTS.md',
+  },
+  cursor: {
+    label: 'Cursor',
+    mode: 'file',
+    target: path.join('.cursor', 'rules', 'total-recall.mdc'),
+    render: instructions => [
+      '---',
+      'description: "Total Recall — Auto-generated behavioral memory surface."',
+      'globs:',
+      'alwaysApply: true',
+      '---',
+      '',
+      instructions
+    ].join('\n')
+  },
+  'claude-code': {
+    label: 'Claude Code',
+    mode: 'symlink',
+    target: 'CLAUDE.md',
+    writeSlashCommands: true
+  },
+  codex: {
+    label: 'Codex',
+    mode: 'symlink',
+    target: 'AGENTS.md'
+  },
+  antigravity: {
+    label: 'Antigravity',
+    mode: 'symlink',
+    target: 'AGENTS.md',
+    writeSlashCommands: true
+  },
+  gemini: {
+    label: 'Gemini',
+    mode: 'symlink',
+    target: 'GEMINI.md',
+    writeSlashCommands: true
+  },
+  aider: {
+    label: 'Aider',
+    mode: 'file',
+    target: '.aider.rules.md',
+    render: instructions => instructions,
+    after: [
+      'Add this to .aider.conf.yml:',
+      '',
+      'read:',
+      '  - .aider.rules.md'
+    ].join('\n')
+  },
+  ultrachat: {
+    label: 'UltraChat',
+    mode: 'api'
+    // No file projection: UltraChat connects via the OpenAI-compatible API.
+    // The compiled INSTRUCTIONS.md is injected per-request by the server.
+    // See docs/guides/ultrachat.md for session sync via /api/sessions/*.
+  },
+  obsidian: {
+    label: 'Obsidian',
+    mode: 'vault',
+    // Symlinks ~/.agent/memory-vault/ into the Obsidian vault as "Total Recall/"
+    // Obsidian indexes all SSSS nodes natively — graph view, backlinks, search.
+    folderName: 'Total Recall'
+  },
+  generic: {
+    label: 'Generic OpenAI-Compatible Client',
+    mode: 'api'
+  }
+};
+
+function parseArgs(args) {
+  const opts = {
+    client: args[0] && !args[0].startsWith('--') ? args[0] : null,
+    brain: null,
+    token: null,
+    vault: null,
+    force: false,
+    json: false,
+    help: false
+  };
+
+  for (let i = opts.client ? 1 : 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--brain': opts.brain = args[++i]; break;
+      case '--token': opts.token = args[++i]; break;
+      case '--vault': opts.vault = args[++i]; break;
+      case '--force': opts.force = true; break;
+      case '--json': opts.json = true; break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+    }
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+  total-recall connect — Configure an IDE or external system
+
+  Usage: total-recall connect <client> [options]
+
+  Clients:
+    cursor
+    claude-code
+    codex
+    antigravity
+    gemini
+    aider
+    ultrachat
+    obsidian
+    generic
+
+  Options:
+    --brain <url>      Brain base URL for API clients
+    --token <token>    Bearer PAT for generated snippets
+    --vault <path>     Obsidian vault path (auto-detected on macOS if omitted)
+    --force            Overwrite generated target files
+    --json             Emit machine-readable connection details
+    --help, -h         Show this help
+`);
+}
+
+function pathExists(filePath) {
+  try {
+    fs.lstatSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      if (!fs.existsSync(destPath)) {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+function bootstrapAgentDir(agentDir) {
+  const brainDir = path.join(agentDir, 'skills', 'total-recall');
+  const vaultCategories = [
+    'invariants', 'patterns', 'anti-patterns',
+    'preferences', 'decisions', 'concepts'
+  ];
+
+  const dirs = [
+    path.join(agentDir, 'skills'),
+    path.join(brainDir, 'memory-derived'),
+    path.join(brainDir, 'memory-inbox', 'pending'),
+    path.join(brainDir, 'memory-inbox', 'conflicts'),
+    path.join(brainDir, 'sessions'),
+    ...vaultCategories.map(c => path.join(brainDir, 'memory-vault', c))
+  ];
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  const scaffoldSkillsDir = path.join(TEMPLATES_DIR, '..', 'scaffold', '.agent', 'skills');
+  let skillsToCopy = ['total-recall'];
+  if (fs.existsSync(scaffoldSkillsDir)) {
+    try {
+      skillsToCopy = fs.readdirSync(scaffoldSkillsDir).filter(f => {
+        return fs.statSync(path.join(scaffoldSkillsDir, f)).isDirectory();
+      });
+    } catch {}
+  }
+
+  for (const skill of skillsToCopy) {
+    const skillSrc = path.join(scaffoldSkillsDir, skill);
+    const skillDest = path.join(agentDir, 'skills', skill);
+    if (fs.existsSync(skillSrc) && !fs.existsSync(path.join(skillDest, 'SKILL.md'))) {
+      copyDirRecursive(skillSrc, skillDest);
+    }
+  }
+}
+
+function readInstructions(cwd, agentDir) {
+  const candidates = [
+    path.join(cwd, 'INSTRUCTIONS.md'),
+    path.join(agentDir, 'INSTRUCTIONS.md')
+  ];
+  const found = candidates.find(file => fs.existsSync(file));
+  if (!found) return null;
+  return fs.readFileSync(found, 'utf8');
+}
+
+function ensureBrainConfig(brainDir, opts) {
+  if (!opts.brain) return null;
+  const configDir = path.join(brainDir, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const config = { url: opts.brain };
+  if (opts.token) config.token = opts.token;
+  const filePath = path.join(configDir, 'brain.json');
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2));
+  return filePath;
+}
+
+function registerClient(brainDir, clientName, preset, projectionPath) {
+  const configDir = path.join(brainDir, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const registryPath = path.join(configDir, 'clients.json');
+  let registry = { clients: {} };
+  if (fs.existsSync(registryPath)) {
+    try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); }
+    catch { /* corrupt file — start fresh */ }
+  }
+  registry.clients ??= {};
+  registry.clients[clientName] = {
+    label: preset.label,
+    mode: preset.mode,
+    projectionPath: projectionPath || null,
+    connectedAt: new Date().toISOString()
+  };
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2), 'utf8');
+}
+
+function writeFileProjection(cwd, preset, instructions, opts) {
+  const targetPath = path.join(cwd, preset.target);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const existed = fs.existsSync(targetPath);
+  if (fs.existsSync(targetPath) && !opts.force) {
+    return { targetPath, action: 'exists' };
+  }
+  const content = preset.render(instructions);
+  fs.writeFileSync(targetPath, content, 'utf8');
+  return { targetPath, action: existed ? 'written' : 'created' };
+}
+
+function writeSymlinkProjection(cwd, preset, opts) {
+  const instructionsPath = path.join(cwd, 'INSTRUCTIONS.md');
+  if (!pathExists(instructionsPath)) {
+    throw new Error(`Cannot create ${preset.target}: ${instructionsPath} does not exist. Run npx total-recall init or compile first.`);
+  }
+
+  const targetPath = path.join(cwd, preset.target);
+  if (pathExists(targetPath)) {
+    if (!opts.force) return { targetPath, action: 'exists' };
+    try {
+      fs.unlinkSync(targetPath);
+    } catch {
+      fs.rmSync(targetPath, { force: true, recursive: true });
+    }
+  }
+  fs.symlinkSync('INSTRUCTIONS.md', targetPath);
+  return { targetPath, action: 'symlinked' };
+}
+
+function apiDetails(opts) {
+  const base = (opts.brain || 'http://127.0.0.1:3000').replace(/\/$/, '');
+  return {
+    base_url: base,
+    chat_completions_url: `${base}/v1/chat/completions`,
+    models_url: `${base}/v1/models`,
+    ssss_manifest_url: `${base}/api/ssss`,
+    discovery_url: `${base}/.well-known/total-recall.json`,
+    authorization_header: opts.token ? `Authorization: Bearer ${opts.token}` : 'Authorization: Bearer <PAT>'
+  };
+}
+
+function detectObsidianVault() {
+  // macOS: Obsidian stores vault paths in its app support config
+  const obsidianConfig = path.join(
+    os.homedir(), 'Library', 'Application Support', 'obsidian', 'obsidian.json'
+  );
+  if (fs.existsSync(obsidianConfig)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(obsidianConfig, 'utf8'));
+      const vaults = Object.values(cfg.vaults || {});
+      // Prefer the most recently opened vault
+      const sorted = vaults.sort((a, b) => (b.ts || 0) - (a.ts || 0));
+      if (sorted.length > 0 && sorted[0].path) return sorted[0].path;
+    } catch { /* ignore parse errors */ }
+  }
+  // Linux: check common locations
+  const xdgConfig = xdgConfigHome;
+  const linuxConfig = path.join(xdgConfig, 'obsidian', 'obsidian.json');
+  if (fs.existsSync(linuxConfig)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(linuxConfig, 'utf8'));
+      const vaults = Object.values(cfg.vaults || {});
+      const sorted = vaults.sort((a, b) => (b.ts || 0) - (a.ts || 0));
+      if (sorted.length > 0 && sorted[0].path) return sorted[0].path;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+function writeVaultProjection(agentDir, preset, opts) {
+  const vaultPath = opts.vault || detectObsidianVault();
+  if (!vaultPath) {
+    throw new Error(
+      'Could not detect an Obsidian vault. Pass --vault <path> to specify one.\n' +
+      '  e.g. total-recall connect obsidian --vault ~/Documents/MyVault'
+    );
+  }
+  if (!fs.existsSync(vaultPath)) {
+    throw new Error(`Obsidian vault not found: ${vaultPath}`);
+  }
+
+  const brainDir = path.join(agentDir, 'skills', 'total-recall');
+  const memoryVault = path.join(brainDir, 'memory-vault');
+  if (!fs.existsSync(memoryVault)) {
+    throw new Error(`Memory vault not found: ${memoryVault}. Run "total-recall init" first.`);
+  }
+
+  const cwd = process.cwd();
+  const isHome = cwd === os.homedir();
+  let folderName = preset.folderName;
+  if (!isHome) {
+    const base = path.basename(cwd);
+    if (base.toLowerCase() === 'ultrachat-ai-powered' || base.toLowerCase() === 'ultrachat') {
+      folderName = 'UltraChat';
+    } else if (base.toLowerCase() === 'total-recall') {
+      folderName = 'Total Recall';
+    } else {
+      folderName = base
+        .split(/[-_]/)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+    }
+  }
+
+  const linkPath = path.join(vaultPath, folderName);
+  if (pathExists(linkPath)) {
+    if (!opts.force) return { targetPath: linkPath, vaultPath, action: 'exists', folderName };
+    try {
+      fs.unlinkSync(linkPath);
+    } catch {
+      fs.rmSync(linkPath, { force: true, recursive: true });
+    }
+  }
+  fs.symlinkSync(memoryVault, linkPath);
+
+  // Install Dataview query dashboard files into memory-vault/queries/
+  // These are TR-native markdown files; Dataview renders them in Obsidian.
+  const queriesTemplateDir = path.join(TEMPLATES_DIR, 'obsidian-queries');
+  const queriesDestDir = path.join(memoryVault, 'queries');
+  if (fs.existsSync(queriesTemplateDir)) {
+    fs.mkdirSync(queriesDestDir, { recursive: true });
+    for (const file of fs.readdirSync(queriesTemplateDir)) {
+      const dest = path.join(queriesDestDir, file);
+      if (!fs.existsSync(dest)) {
+        fs.copyFileSync(path.join(queriesTemplateDir, file), dest);
+      }
+    }
+  }
+
+  return { targetPath: linkPath, vaultPath, action: 'symlinked', folderName };
+}
+
+function printApiSnippet(client, details) {
+  console.log(`\n  ${client.label} connection details\n`);
+  console.log(`  Discovery: ${details.discovery_url}`);
+  console.log(`  Models:    ${details.models_url}`);
+  console.log(`  Chat:      ${details.chat_completions_url}`);
+  console.log(`  SSSS:      ${details.ssss_manifest_url}`);
+  console.log(`  Auth:      ${details.authorization_header}`);
+  console.log('\n  OpenAI-compatible config:');
+  console.log(`    baseURL: ${details.base_url}/v1`);
+  console.log('    model:   total-recall/gemma4');
+}
+
+function writeClaudeCodeSlashCommands(opts) {
+  const commandsDir = path.join(os.homedir(), '.claude', 'commands');
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  const base = (opts.brain || 'http://127.0.0.1:3000').replace(/\/$/, '');
+  const authHeader = 'Authorization: Bearer <YOUR_PAT_TOKEN>';
+
+  const commands = [
+    {
+      file: 'memory.md',
+      description: 'Search or manage Total Recall memory',
+      body: `Search or manage your Total Recall memory via the REST API.
+
+Brain URL: ${base}
+Auth header: ${authHeader}
+
+Usage examples (pass as arguments):
+  search <query>     — semantic search across all memory nodes
+  list               — list all nodes
+  add <title> <body> — create a new memory node
+
+Call \`${base}/api/memory/search\` with body \`{"query":"$ARGUMENTS"}\` to search.
+Call \`${base}/api/memory\` with POST to add nodes.
+Always include the Authorization header above.
+
+$ARGUMENTS`
+    },
+    {
+      file: 'brain.md',
+      description: 'Show Total Recall brain status and health',
+      body: `Check your Total Recall brain status.
+
+Brain URL: ${base}
+Auth header: ${authHeader}
+
+Fetch \`${base}/health\` and \`${base}/api/health\` to check server health.
+Fetch \`${base}/.well-known/total-recall.json\` for the full capability manifest.
+Report: server status, model loaded, vault node count, connected clients.
+
+$ARGUMENTS`
+    },
+    {
+      file: 'vault.md',
+      description: 'Compile or inspect Total Recall memory vault',
+      body: `Compile or inspect the Total Recall SSSS memory vault.
+
+Brain URL: ${base}
+Auth header: ${authHeader}
+
+Commands (pass as argument):
+  compile            — POST ${base}/api/vault/compile  to rebuild INSTRUCTIONS.md
+  nodes              — GET  ${base}/api/vault/nodes    to list all SSSS nodes
+  surface            — GET  ${base}/api/vault/surface  to read compiled surface
+
+$ARGUMENTS`
+    },
+    {
+      file: 'ssss.md',
+      description: 'Explore the SSSS cognitive graph, backlinks, and topological structure',
+      body: `Explore and manage your SSSS cognitive graph, Obsidian canvas, and backlinks.
+
+Brain URL: ${base}
+Auth header: ${authHeader}
+
+Commands (pass as argument):
+  help                 — Learn SSSS categories, frontmatter rules, and schema specs.
+  stats                — Get deep network topology metrics (Total links, unlinked Orphans, connected Hubs).
+  map <slug>           — Render bidirectional incoming/outgoing graph connections for a slug.
+  compile              — Recompiles derived indices and regenerates the high-fidelity Obsidian Canvas.
+
+Examples:
+  /ssss stats
+  /ssss map atomic-writes
+  /ssss compile
+
+If the argument is "compile", perform a POST to \`${base}/api/vault/compile\`.
+Otherwise, run \`npx total-recall map --relations\` or execute curl queries to list network metrics.
+
+$ARGUMENTS`
+    },
+    {
+      file: 'recall.md',
+      description: 'Ask Total Recall brain a question or run a task',
+      body: `Send a message to your Total Recall brain.
+
+Brain URL: ${base}
+Auth header: ${authHeader}
+
+POST to \`${base}/v1/chat/completions\` with:
+  model: "total-recall"
+  messages: [{"role":"user","content":"$ARGUMENTS"}]
+
+Include the Authorization header. Stream the response if possible.
+
+$ARGUMENTS`
+    }
+  ];
+
+  const written = [];
+  for (const cmd of commands) {
+    const filePath = path.join(commandsDir, cmd.file);
+    const content = `---\ndescription: "${cmd.description}"\n---\n${cmd.body}\n`;
+    const existed = fs.existsSync(filePath);
+    if (!existed || opts.force) {
+      fs.writeFileSync(filePath, content, 'utf8');
+      written.push({ file: cmd.file, action: existed ? 'updated' : 'created' });
+    } else {
+      written.push({ file: cmd.file, action: 'exists' });
+    }
+  }
+  return written;
+}
+
+function writeGeminiSlashCommands(opts) {
+  const globalDir = path.join(os.homedir(), '.gemini', 'commands');
+  const localDir = path.join(process.cwd(), '.gemini', 'commands');
+
+  fs.mkdirSync(globalDir, { recursive: true });
+  fs.mkdirSync(localDir, { recursive: true });
+
+  const base = (opts.brain || 'http://127.0.0.1:3000').replace(/\/$/, '');
+  const token = '<YOUR_PAT_TOKEN>';
+
+  const commands = {
+    'memory.toml': {
+      description: 'Search or manage Total Recall memory',
+      prompt: `You are Antigravity, an AI assistant with the Total Recall SSSS v2 memory vault.
+Search the semantic memory vault or fetch nodes using the following query:
+{{args}}
+
+Instructions:
+Perform a POST request to \`${base}/api/memory/search/semantic\` with the body \`{"query": "{{args}}", "top_k": 5}\` and Authorization: Bearer ${token}.`
+    },
+    'brain.toml': {
+      description: 'Show Total Recall brain status and health',
+      prompt: `Show the health, loaded model status, and statistics of the local Total Recall Sovereign OS brain.
+
+Instructions:
+Query the health of the local brain by sending a GET request to \`${base}/health\` with Authorization: Bearer ${token}.`
+    },
+    'vault.toml': {
+      description: 'Compile or inspect the Total Recall SSSS memory vault',
+      prompt: `Compile, rebuild, or inspect the Structured Semantic Syntax System (SSSS) memory vault.
+
+Instructions:
+1. If the argument is "compile", send a POST request to \`${base}/api/vault/compile\` with Authorization: Bearer ${token} or run \`npx total-recall compile\`.
+2. If the argument is "nodes", send a GET request to \`${base}/api/memory\` with Authorization: Bearer ${token}.
+3. Summarize the changes and verify rule propagation across the workspace.`
+    },
+    'ssss.toml': {
+      description: 'Explore SSSS cognitive graph, backlinks, and network statistics',
+      prompt: `You are Antigravity, an AI assistant with the Total Recall SSSS v2 memory vault.
+Explore the SSSS cognitive graph, backlinks, and network topology using the query:
+{{args}}
+
+Instructions:
+1. Parse the arguments.
+2. If "stats", run \`npx total-recall map --relations\` to retrieve and summarize cognitive graph metrics, Highly Connected Hubs, and unlinked Orphans.
+3. If "map <slug>", print the inbound backlinks and outbound relations for the specified memory node slug using \`npx total-recall map --relations\`.
+4. If "compile", send a POST request to \`${base}/api/vault/compile\` with Authorization: Bearer ${token} or run \`npx total-recall compile\`.
+5. If "help", explain the SSSS v2 specification, categories (invariants, preferences, anti-patterns, patterns, decisions, concepts, facts, lore) and the bidirectional backlink structure.`
+    },
+    'recall.toml': {
+      description: 'Ask Total Recall brain a question or run a specialized agent task',
+      prompt: `Send a direct conversational query or task instruction to the Total Recall local brain.
+Query: {{args}}
+
+Instructions:
+1. Query the memory vault for relevant context by sending a POST request to \`${base}/api/memory/search/semantic\` with the body \`{"query": "{{args}}", "top_k": 5}\` and Authorization: Bearer ${token}.
+2. Address the user's inquiry thoroughly, referencing active memory nodes where applicable.`
+    }
+  };
+
+  const written = [];
+  for (const [filename, cmd] of Object.entries(commands)) {
+    const tomlContent = `description = "${cmd.description}"\nprompt = """\n${cmd.prompt}\n"""\n`;
+
+    // Write global command
+    const globalPath = path.join(globalDir, filename);
+    const globalExisted = fs.existsSync(globalPath);
+    if (!globalExisted || opts.force) {
+      fs.writeFileSync(globalPath, tomlContent, 'utf8');
+      written.push({ file: `global/${filename}`, action: globalExisted ? 'updated' : 'created' });
+    } else {
+      written.push({ file: `global/${filename}`, action: 'exists' });
+    }
+
+    // Write local command
+    const localPath = path.join(localDir, filename);
+    const localExisted = fs.existsSync(localPath);
+    if (!localExisted || opts.force) {
+      fs.writeFileSync(localPath, tomlContent, 'utf8');
+      written.push({ file: `local/${filename}`, action: localExisted ? 'updated' : 'created' });
+    } else {
+      written.push({ file: `local/${filename}`, action: 'exists' });
+    }
+  }
+
+  return written;
+}
+
+
+export default async function connect(args) {
+  const opts = parseArgs(args);
+  if (opts.help || !opts.client) {
+    printHelp();
+    return;
+  }
+
+  const preset = CLIENTS[opts.client];
+  if (!preset) {
+    console.error(`Unknown client: ${opts.client}`);
+    console.error(`Supported clients: ${Object.keys(CLIENTS).join(', ')}`);
+    process.exit(1);
+  }
+
+
+  const cwd = process.cwd();
+  const isHome = cwd === os.homedir();
+  const agentDir = process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR || (isHome ? configAgentDir : path.join(cwd, '.agent'));
+  const brainDir = path.join(agentDir, 'skills', 'total-recall');
+
+  // Auto-resolve brain URL and token if not explicitly provided
+  if (!opts.brain) {
+    if (trBrain) {
+      opts.brain = trBrain;
+    } else {
+      const globalAgentDir = path.join(os.homedir(), '.agent');
+      const candidateConfigDirs = [
+        path.join(brainDir, 'config'),
+        path.join(globalAgentDir, 'skills', 'total-recall', 'config')
+      ];
+
+      for (const dir of candidateConfigDirs) {
+        const brainJsonPath = path.join(dir, 'brain.json');
+        if (fs.existsSync(brainJsonPath)) {
+          try {
+            const cfg = JSON.parse(fs.readFileSync(brainJsonPath, 'utf8'));
+            if (cfg.url) {
+              opts.brain = cfg.url;
+              break;
+            }
+          } catch { /* ignore */ }
+        }
+      }
+
+      if (!opts.brain) {
+        for (const dir of candidateConfigDirs) {
+          const wizardJsonPath = path.join(dir, 'wizard-config.json');
+          if (fs.existsSync(wizardJsonPath)) {
+            try {
+              const cfg = JSON.parse(fs.readFileSync(wizardJsonPath, 'utf8'));
+              if (cfg.apiUrl) {
+                opts.brain = cfg.apiUrl;
+                break;
+              }
+            } catch { /* ignore */ }
+          }
+        }
+      }
+    }
+  }
+  if (!opts.brain) {
+    opts.brain = 'http://127.0.0.1:3000';
+  }
+
+  if (!opts.token) {
+    if (trPat) {
+      opts.token = trPat;
+    } else {
+      const globalAgentDir = path.join(os.homedir(), '.agent');
+      const candidateConfigDirs = [
+        path.join(brainDir, 'config'),
+        path.join(globalAgentDir, 'skills', 'total-recall', 'config')
+      ];
+
+      for (const dir of candidateConfigDirs) {
+        const brainJsonPath = path.join(dir, 'brain.json');
+        if (fs.existsSync(brainJsonPath)) {
+          try {
+            const cfg = JSON.parse(fs.readFileSync(brainJsonPath, 'utf8'));
+            if (cfg.token) {
+              opts.token = cfg.token;
+              break;
+            }
+          } catch { /* ignore */ }
+        }
+      }
+    }
+  }
+
+  // Dynamic bootstrapping and compilation if INSTRUCTIONS.md is missing from both candidate paths
+  const instructionsCandidates = [
+    path.join(cwd, 'INSTRUCTIONS.md'),
+    path.join(agentDir, 'INSTRUCTIONS.md')
+  ];
+  if (!instructionsCandidates.some(f => pathExists(f))) {
+    try {
+      bootstrapAgentDir(agentDir);
+      const { compileSurface } = await import('../core/surface.mjs');
+      const instructionsFile = path.join(cwd, 'INSTRUCTIONS.md');
+      const vaultDir = path.join(brainDir, 'memory-vault');
+      const skillsDir = path.join(agentDir, 'skills');
+      const derivedDir = path.join(brainDir, 'memory-derived');
+      await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile });
+    } catch {
+      // Fallback: seed a clean, basic default SSSS instructions file so connection is never blocked
+      const instructionsFile = path.join(cwd, 'INSTRUCTIONS.md');
+      const defaultContent = `# Tier 1 Invariants (Total Recall Hot Memory)\n\n## ⚡ Before You Respond\n1. Always be thorough.\n2. Do not add placeholders.\n`;
+      fs.writeFileSync(instructionsFile, defaultContent, 'utf8');
+    }
+  }
+
+  const brainConfigPath = ensureBrainConfig(brainDir, opts);
+  const details = apiDetails(opts);
+  const result = {
+    client: opts.client,
+    label: preset.label,
+    mode: preset.mode,
+    brain_config_path: brainConfigPath,
+    api: details,
+    projection: null,
+    notes: []
+  };
+
+  if (preset.mode === 'file') {
+    const instructions = readInstructions(cwd, agentDir);
+    if (!instructions) {
+      throw new Error('No INSTRUCTIONS.md found. Run npx total-recall init or compile before connecting file-based IDEs.');
+    }
+    result.projection = writeFileProjection(cwd, preset, instructions, opts);
+  } else if (preset.mode === 'symlink') {
+    result.projection = writeSymlinkProjection(cwd, preset, opts);
+  } else if (preset.mode === 'global-symlink') {
+    // Pi: symlink ~/.pi/agent/AGENTS.md → compiled INSTRUCTIONS.md
+    const instructionsPath = path.join(cwd, 'INSTRUCTIONS.md');
+    if (!pathExists(instructionsPath)) {
+      throw new Error(`No INSTRUCTIONS.md found. Run npx total-recall init or compile first.`);
+    }
+    const targetPath = preset.globalTarget;
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    if (pathExists(targetPath)) {
+      if (!opts.force) {
+        result.projection = { targetPath, action: 'exists' };
+      } else {
+        try {
+          fs.unlinkSync(targetPath);
+        } catch {
+          fs.rmSync(targetPath, { force: true, recursive: true });
+        }
+        fs.symlinkSync(instructionsPath, targetPath);
+        result.projection = { targetPath, action: 'symlinked' };
+      }
+    } else {
+      fs.symlinkSync(instructionsPath, targetPath);
+      result.projection = { targetPath, action: 'symlinked' };
+    }
+    result.notes.push(`  ~/.pi/agent/AGENTS.md → ${instructionsPath}`);
+  } else if (preset.mode === 'hermes') {
+    // Hermes: write compiled MEMORY.md to ~/.hermes/memories/MEMORY.md (max 2200 chars)
+    const instructions = readInstructions(cwd, agentDir);
+    if (!instructions) throw new Error('No INSTRUCTIONS.md found. Run npx total-recall init or compile first.');
+    fs.mkdirSync(path.dirname(preset.memoryPath), { recursive: true });
+    const capped = instructions.slice(0, 2200);
+    fs.writeFileSync(preset.memoryPath, capped, 'utf8');
+    result.projection = { targetPath: preset.memoryPath, action: 'written' };
+    result.notes.push(`  Hermes MEMORY.md (${capped.length} chars) → ${preset.memoryPath}`);
+    result.notes.push('  Note: Hermes has a 2,200-char limit on MEMORY.md. Total Recall auto-caps this.');
+  } else if (preset.mode === 'openclaw') {
+    // OpenClaw: write MEMORY.md + symlink AGENTS.md in cwd
+    const instructions = readInstructions(cwd, agentDir);
+    if (!instructions) throw new Error('No INSTRUCTIONS.md found. Run npx total-recall init or compile first.');
+    // MEMORY.md — curated facts extracted from instructions
+    const memPath = path.join(cwd, preset.memoryTarget);
+    if (!fs.existsSync(memPath) || opts.force) {
+      fs.writeFileSync(memPath, instructions, 'utf8');
+    }
+    // AGENTS.md — symlink to INSTRUCTIONS.md
+    const agentsPath = path.join(cwd, preset.agentsTarget);
+    if (pathExists(agentsPath)) {
+      if (opts.force) {
+        try {
+          fs.unlinkSync(agentsPath);
+        } catch {
+          fs.rmSync(agentsPath, { force: true, recursive: true });
+        }
+        fs.symlinkSync('INSTRUCTIONS.md', agentsPath);
+      }
+    } else {
+      fs.symlinkSync('INSTRUCTIONS.md', agentsPath);
+    }
+    result.projection = { targetPath: memPath, action: 'written' };
+    result.notes.push(`  OpenClaw MEMORY.md written to ${memPath}`);
+    result.notes.push(`  OpenClaw AGENTS.md → INSTRUCTIONS.md`);
+  } else if (preset.mode === 'vault') {
+    result.projection = writeVaultProjection(agentDir, preset, opts);
+    const folderName = result.projection.folderName || preset.folderName;
+    result.notes.push([
+      `  Vault linked: ${result.projection.vaultPath}/${folderName}/`,
+      `  → ${path.join(brainDir, 'memory-vault')}`,
+      '',
+      `  Open Obsidian and look for the "${folderName}" folder.`,
+      '  All SSSS memory nodes are visible in Graph View, Search, and Backlinks.',
+      '',
+      '  To back up via Obsidian Sync or iCloud, enable sync in Obsidian — the',
+      `  symlinked folder will be included automatically.`
+    ].join('\n'));
+  }
+
+  if (preset.after) result.notes.push(preset.after);
+
+  // Write slash commands
+  if (preset.writeSlashCommands) {
+    if (opts.client === 'antigravity' || opts.client === 'gemini') {
+      const slashResults = writeGeminiSlashCommands(opts);
+      result.slash_commands = slashResults;
+      const created = slashResults.filter(r => r.action !== 'exists');
+      if (created.length > 0) {
+        result.notes.push(`  Slash commands written to ~/.gemini/commands/ and .gemini/commands/:\n` +
+          created.map(r => `    ${r.file} (${r.action})`).join('\n'));
+      }
+    } else {
+      const slashResults = writeClaudeCodeSlashCommands(opts);
+      result.slash_commands = slashResults;
+      const created = slashResults.filter(r => r.action !== 'exists');
+      if (created.length > 0) {
+        result.notes.push(`  Slash commands written to ~/.claude/commands/:\n` +
+          created.map(r => `    /${r.file.replace('.md', '')} (${r.action})`).join('\n'));
+      }
+    }
+  }
+
+  // Record this client in the registry so `status` can report freshness
+  registerClient(brainDir, opts.client, preset, result.projection?.targetPath || null);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`\n  Total Recall connected: ${preset.label}`);
+  if (result.projection) {
+    const action = result.projection.action;
+    const target = result.projection.targetPath;
+    const display = preset.mode === 'vault' ? target : path.relative(cwd, target);
+    console.log(`  Projection: ${action} ${display}`);
+  }
+  if (brainConfigPath) {
+    console.log(`  Brain config: ${brainConfigPath}`);
+  }
+  if (preset.mode !== 'vault') {
+    printApiSnippet(preset, details);
+  }
+  for (const note of result.notes) {
+    console.log(`\n${note}`);
+  }
+  console.log();
+}