total-recall-brain 3.1.0

package/src/cli/doctor.mjs

@@ -0,0 +1,254 @@
+/**
+ * total-recall doctor
+ *
+ * System diagnostic utility to pre-flight check all dependencies,
+ * hardware requirements, software binaries, port conflicts, and model servers
+ * before doing a full deployment or initialization.
+ *
+ * Usage:
+ *   npx total-recall doctor
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import net from 'node:net';
+import child_process from 'node:child_process';
+
+// ─── Formatting & UI Helpers ────────────────────────────────────────────────
+function log(msg)     { console.log(`  ${msg}`); }
+function logOk(msg)   { console.log(`  ✅ \x1b[32m${msg}\x1b[0m`); }
+function logWarn(msg) { console.log(`  ⚠️  \x1b[33m${msg}\x1b[0m`); }
+function logFail(msg) { console.log(`  ❌ \x1b[31m${msg}\x1b[0m`); }
+function logInfo(msg) { console.log(`  ℹ  \x1b[34m${msg}\x1b[0m`); }
+
+function hr() {
+  console.log('  ' + '─'.repeat(58));
+}
+
+function commandExists(cmd) {
+  if (!cmd || !/^[a-zA-Z0-9_-]+$/.test(cmd)) {
+    return false;
+  }
+  try {
+    child_process.execFileSync('which', [cmd], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getSystemRamGb() {
+  return Math.round(os.totalmem() / (1024 * 1024 * 1024));
+}
+
+function checkPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(false); // Port taken
+      } else {
+        resolve(true); // Other error (e.g. permission), treat as unavailable for binding
+      }
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(true)); // Port free
+    });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+// ─── Main Doctor Routine ─────────────────────────────────────────────────────
+export default async function doctor() {
+  console.log(`
+  ┌─────────────────────────────────────────────────────────┐
+  │  Total Recall System Doctor                             │
+  │  Pre-flighting sovereign runtime diagnostics...         │
+  └─────────────────────────────────────────────────────────┘
+`);
+
+  let warnings = 0;
+  let failures = 0;
+
+  // ── Step 1: System Hardware Check ──
+  hr();
+  logInfo('1. HARDWARE COMPATIBILITY DIAGNOSTICS');
+  
+  const platform = os.platform();
+  const arch = os.arch();
+  const cpus = os.cpus().length;
+  const ramGb = getSystemRamGb();
+
+  log(`Platform:      ${platform} (${arch})`);
+  log(`CPU Cores:     ${cpus} threads`);
+  log(`Total Memory:  ${ramGb} GB RAM`);
+
+  if (ramGb >= 4) {
+    logOk('System RAM is fully sufficient for headless CLI agent dispatch (≥4 GB)');
+  } else if (ramGb >= 2) {
+    logWarn(`System RAM (${ramGb} GB) is slightly low, but sufficient for headless execution.`);
+    warnings++;
+  } else {
+    logFail(`System RAM (${ramGb} GB) is critically low.`);
+    failures++;
+  }
+
+  // ── Step 2: Binary Dependencies ──
+  hr();
+  logInfo('2. SOFTWARE DEPENDENCY CHECK');
+
+  const dependencies = [
+    { name: 'git', required: true, desc: 'sync and backup operations' },
+    { name: 'curl', required: true, desc: 'REST communications & API fetches' },
+    { name: 'python3', required: true, desc: 'native SearXNG search engine' },
+    { name: 'pip3', required: false, desc: 'SearXNG package installation (fallback to python3 -m pip)' },
+    { name: 'caddy', required: false, desc: 'auto-TLS reverse proxying' },
+    { name: 'docker', required: false, desc: 'containerized fallback services' },
+  ];
+
+  for (const dep of dependencies) {
+    const present = commandExists(dep.name === 'pip3' ? 'pip' : dep.name);
+    if (present) {
+      logOk(`${dep.name.padEnd(8)}: Present`);
+    } else {
+      if (dep.required) {
+        logFail(`${dep.name.padEnd(8)}: MISSING — Required for ${dep.desc}`);
+        failures++;
+      } else {
+        logWarn(`${dep.name.padEnd(8)}: Missing (Optional — used for ${dep.desc})`);
+        warnings++;
+      }
+    }
+  }
+
+  // Check python venv capability
+  if (commandExists('python3')) {
+    try {
+      child_process.execSync('python3 -c "import venv"', { stdio: 'ignore' });
+      logOk('python-venv: Installed');
+    } catch {
+      logFail('python-venv: MISSING — Required for local SearXNG deployment');
+      log('     Tip: Run: apt-get install -y python3-venv');
+      failures++;
+    }
+  }
+
+  // ── Step 3: Network Port Conflicts ──
+  hr();
+  logInfo('3. NETWORKING PORT AVAILABILITY');
+
+  const ports = [
+    { num: 3000, desc: 'Total Recall API Server', critical: true },
+    { num: 8888, desc: 'SearXNG Web Search Engine', critical: false },
+    { num: 80, desc: 'HTTP Caddy redirection (Let\'s Encrypt)', critical: false },
+    { num: 443, desc: 'HTTPS Caddy TLS ingress', critical: false },
+  ];
+
+  for (const port of ports) {
+    const free = await checkPort(port.num);
+    if (free) {
+      logOk(`Port ${String(port.num).padEnd(5)}: Free (${port.desc})`);
+    } else {
+      if (port.critical) {
+        logFail(`Port ${String(port.num).padEnd(5)}: CONFLICT — Already bound by another service (${port.desc})`);
+        failures++;
+      } else {
+        logWarn(`Port ${String(port.num).padEnd(5)}: In use (${port.desc})`);
+        warnings++;
+      }
+    }
+  }
+
+  // ── Step 4: CLI Agents & Embeddings Providers ──
+  hr();
+  logInfo('4. CLI AGENTS & EMBEDDINGS PROVIDERS');
+
+  const { loadRuntimeConfig } = await import('../core/runtime.mjs');
+  let config;
+  try {
+    config = loadRuntimeConfig();
+  } catch (err) {
+    config = { agents: [] };
+  }
+  const agents = config.agents || [];
+
+  if (agents.length > 0) {
+    let healthyCount = 0;
+    for (const agent of agents) {
+      const exists = commandExists(agent.binary);
+      if (exists) {
+        logOk(`Agent ${agent.name.padEnd(8)}: Available (Binary: ${agent.binary})`);
+        healthyCount++;
+      } else {
+        logWarn(`Agent ${agent.name.padEnd(8)}: NOT FOUND in PATH (Binary: ${agent.binary})`);
+        warnings++;
+      }
+    }
+  } else {
+    logWarn('No CLI agents found in registry configuration.');
+    warnings++;
+  }
+
+  const googleKey = process.env.GOOGLE_API_KEY;
+  const openaiKey = process.env.OPENAI_API_KEY;
+  
+  if (googleKey) {
+    logOk('GOOGLE_API_KEY environment variable is configured (Primary Embeddings)');
+  } else if (openaiKey) {
+    logOk('OPENAI_API_KEY environment variable is configured (Fallback Embeddings)');
+  } else {
+    logWarn('Neither GOOGLE_API_KEY nor OPENAI_API_KEY is configured in the environment.');
+    log('     Tip: Configure GOOGLE_API_KEY to use gemini-embedding-2 (free tier).');
+    warnings++;
+  }
+
+  // ── Step 5: Privilege & Workspace Environment ──
+  hr();
+  logInfo('5. SECURITY & WORKSPACE INTEGRITY');
+
+  // VFS permissions
+  const home = os.homedir();
+  const vfsPath = path.join(home, '.agent');
+  if (fs.existsSync(vfsPath)) {
+    try {
+      fs.accessSync(vfsPath, fs.constants.R_OK | fs.constants.W_OK);
+      logOk('VFS folder permissions (~/.agent): Read/Write Stable');
+    } catch {
+      logFail('VFS folder permissions (~/.agent): ACCESS DENIED');
+      failures++;
+    }
+  } else {
+    logOk('VFS folder (~/.agent): Ready to scaffold');
+  }
+
+  // Sudo access (non-blocking check)
+  if (platform === 'linux') {
+    try {
+      child_process.execSync('sudo -n true', { stdio: 'ignore' });
+      logOk('Sudo access: Passwordless sudo enabled (ideal for automated deploy)');
+    } catch {
+      logWarn('Sudo access: Passwordless sudo disabled (deployment will prompt for root password)');
+      warnings++;
+    }
+  }
+
+  // ── Diagnostics Summary ──
+  hr();
+  console.log('\n  ┌─────────────────────────────────────────────────────────┐');
+  if (failures === 0 && warnings === 0) {
+    console.log('  │  🎉 Diagnostics Passed! System is perfectly healthy.     │');
+    console.log('  │  Ready for npx total-recall setup or deploy.            │');
+  } else if (failures === 0) {
+    console.log(`  │  ⚠️  Diagnostics passed with ${warnings} warning(s).                 │`);
+    console.log('  │  System is ready, but check recommendations above.      │');
+  } else {
+    console.log(`  │  ❌ Diagnostics failed with ${failures} error(s) and ${warnings} warning(s).    │`);
+    console.log('  │  Please resolve critical failures before deploying.     │');
+  }
+  console.log('  └─────────────────────────────────────────────────────────┘\n');
+
+  if (failures > 0) {
+    process.exitCode = 1;
+  }
+}

package/src/cli/dream.mjs

@@ -0,0 +1,80 @@
+/**
+ * total-recall dream
+ *
+ * Manually trigger a single dream cycle (Light → REM → Deep Sleep).
+ *
+ * Usage:
+ *   npx total-recall dream [options]
+ *
+ * Options:
+ *   --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
+ *   --help             Show this help
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = resolveAgentDir();
+const BRAIN_DIR = resolveBrainDir();
+
+function parseArgs(args) {
+  const opts = { vault: null, help: false };
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--vault': opts.vault = args[++i]; break;
+      case '--help': case '-h': opts.help = true; break;
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+  total-recall dream — Manually trigger a dream cycle
+
+  The dream cycle runs three phases:
+    1. Light Sleep — Scan vault for recent modifications
+    2. REM         — Score, conflict-check, and promote/decay candidates
+    3. Deep Sleep  — Recompile the surface (indexes + INSTRUCTIONS.md)
+
+  Usage: total-recall dream [options]
+
+  Options:
+    --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
+    --help, -h         Show this help
+`);
+}
+
+export default async function dream(args) {
+  const opts = parseArgs(args);
+  if (opts.help) { printHelp(); return; }
+
+  const vaultDir = opts.vault || path.join(BRAIN_DIR, 'memory-vault');
+  const skillsDir = path.join(AGENT_DIR, 'skills');
+  const derivedDir = path.join(BRAIN_DIR, 'memory-derived');
+  const conflictsDir = path.join(BRAIN_DIR, 'memory-inbox', 'conflicts');
+  const instructionsFile = path.join(AGENT_DIR, 'INSTRUCTIONS.md');
+
+  console.error('\n  🌙 Starting dream cycle...\n');
+  const startTime = Date.now();
+
+  try {
+    const { runDreamCycle } = await import('../core/dream.mjs');
+    const result = await runDreamCycle({
+      vaultDir,
+      skillsDir,
+      derivedDir,
+      conflictsDir,
+      instructionsFile,
+    });
+
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.error(`\n  ✅ Dream cycle complete (${elapsed}s) — status: ${result.status}`);
+  } catch (err) {
+    console.error(`\n  ❌ Dream cycle failed: ${err.message}`);
+    console.error(err.stack);
+    process.exit(1);
+  }
+}

package/src/cli/forget.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
+import { compileSurface } from '../core/surface.mjs';
+import { deleteNode, loadNodes } from '../core/vault.mjs';
+
+function printHelp() {
+  console.log(`
+  total-recall forget — Delete a memory node by slug
+
+  Usage: total-recall forget <slug> [options]
+
+  Options:
+    --global              Delete from the global brain
+    --project             Delete from the project brain
+    --no-compile          Skip auto-recompilation after deletion
+    --help, -h            Show this help
+
+  If neither --global nor --project is specified, the node is searched in the
+  project brain first (if one exists), then falls back to global.
+
+  Examples:
+    npx total-recall forget test-propagation-delete-me
+    npx total-recall forget old-invariant --global
+    npx total-recall forget stale-fact --project
+    npx total-recall forget my-node --no-compile
+`);
+}
+
+export default async function forget(args) {
+  const { layer: explicitLayer, remainingArgs } = parseLayerFlag(args);
+
+  const slug = remainingArgs[0];
+  const noCompile = remainingArgs.includes('--no-compile');
+
+  if (!slug || slug === '--help' || slug === '-h') {
+    printHelp();
+    return;
+  }
+
+  let layer = explicitLayer;
+
+  // Auto-detect which layer contains the node
+  if (layer === 'auto') {
+    const brains = getBothBrains();
+    // Check project first, then global
+    if (brains.project) {
+      const projVaultDir = path.join(brains.project.brainDir, 'memory-vault');
+      const projNodes = loadNodes(projVaultDir);
+      if (projNodes.some(n => n.slug === slug)) {
+        layer = 'project';
+      }
+    }
+    if (layer === 'auto') {
+      layer = 'global';
+    }
+  }
+
+  const resolvedBrainDir = resolveBrainDir(layer);
+  const resolvedAgentDir = resolveAgentDir(layer);
+  const vaultDir = path.join(resolvedBrainDir, 'memory-vault');
+  const derivedDir = path.join(resolvedBrainDir, 'memory-derived');
+  const skillsDir = path.join(resolvedAgentDir, 'skills');
+  const instructionsFile = path.join(resolvedAgentDir, 'INSTRUCTIONS.md');
+  const layerLabel = layer === 'project' ? '[project]' : '[global]';
+
+  // Attempt deletion
+  const deleted = deleteNode(slug, vaultDir);
+
+  if (!deleted) {
+    console.error(`  ❌ Node "${slug}" not found in ${layerLabel} vault at ${vaultDir}`);
+    process.exit(1);
+  }
+
+  console.log(`  ✅ Deleted memory node "${slug}" from ${layerLabel} vault.`);
+
+  // Recompile unless --no-compile
+  if (!noCompile) {
+    console.log('  ⏳ Recompiling active memory surfaces and indexes...');
+    try {
+      const compileResult = await compileSurface({
+        vaultDir,
+        skillsDir,
+        derivedDir,
+        instructionsFile
+      });
+      console.log(`  ✅ Recompilation successful! Processed ${compileResult.nodesProcessed} SSSS nodes.`);
+    } catch (err) {
+      console.warn(`  ⚠️  Node deleted, but surface recompilation failed: ${err.message}`);
+    }
+  }
+}

package/src/cli/friction.mjs

@@ -0,0 +1,21 @@
+import { detectFriction } from '../core/friction.mjs';
+import path from 'path';
+import { resolveBrainDir } from './agent-dir.mjs';
+
+/**
+ * CLI command to run Friction Detection on logs
+ */
+export default async function runFriction(args) {
+  console.log(`[Friction] 🔍 Analyzing logs for workflow bottlenecks...`);
+  
+  // Default path for watchdog logs
+  const logPath = args[0] || path.join(resolveBrainDir(), 'logs', 'watchdog.jsonl');
+  
+  const result = await detectFriction(logPath);
+  if (!result) {
+    console.log(`[Friction] No logs found at ${logPath}. Skipping analysis.`);
+    return;
+  }
+  
+  console.log(`\n${result.report}`);
+}

package/src/cli/generate-pat.mjs

@@ -0,0 +1,65 @@
+import { issueKey } from '../server/keys.mjs';
+
+function parseName(args) {
+  const idx = args.indexOf('--name');
+  if (idx !== -1 && args[idx + 1]) return args[idx + 1];
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (['--scope', '--scopes', '--expires'].includes(args[i])) {
+      i++;
+      continue;
+    }
+    if (!args[i].startsWith('--')) positional.push(args[i]);
+  }
+  return positional.join(' ').trim() || 'CLI Key';
+}
+
+function parseScopes(args) {
+  const idx = args.indexOf('--scope');
+  if (idx !== -1 && args[idx + 1]) return args[idx + 1].split(',').map(scope => scope.trim());
+  const scopesIdx = args.indexOf('--scopes');
+  if (scopesIdx !== -1 && args[scopesIdx + 1]) return args[scopesIdx + 1].split(',').map(scope => scope.trim());
+  return ['*'];
+}
+
+function parseExpiresAt(args) {
+  const idx = args.indexOf('--expires');
+  if (idx === -1 || !args[idx + 1]) return null;
+  const value = args[idx + 1];
+  if (/^\d+d$/.test(value)) {
+    const days = Number(value.slice(0, -1));
+    return new Date(Date.now() + days * 86400000).toISOString();
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+  return value;
+}
+
+export default async function generatePat(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  total-recall generate-pat --name "codex"
+  total-recall generate-pat --name "readonly" --scope "models:read,ssss:read,memory:read"
+  total-recall generate-pat --name "temp" --expires 30d
+
+  Issues a Personal Access Token and stores only its hash in
+  ~/.agent/config/keys.jsonl. The token is printed once.
+
+  Options:
+    --name <name>       Human-readable key name
+    --scope <list>      Comma-separated scopes (default: *)
+    --scopes <list>     Alias for --scope
+    --expires <date>    ISO date or relative days, e.g. 2026-06-01 or 30d
+`);
+    return;
+  }
+
+  const key = issueKey(parseName(args), {
+    scopes: parseScopes(args),
+    expires_at: parseExpiresAt(args)
+  });
+  console.log(`Name:  ${key.name}`);
+  console.log(`ID:    ${key.id}`);
+  console.log(`Scopes: ${key.scopes.join(', ')}`);
+  console.log(`Expires: ${key.expires_at || 'never'}`);
+  console.log(`Token: ${key.token}`);
+}

package/src/cli/hash-password.mjs

@@ -0,0 +1,22 @@
+import bcrypt from 'bcrypt';
+import { BCRYPT_COST } from '../server/auth.mjs';
+
+export default async function hashPassword(args) {
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    console.log(`
+  total-recall hash-password "new dashboard password"
+
+  Prints a bcrypt hash for ~/.agent/config/security.yml dashboard.password_hash.
+`);
+    return;
+  }
+
+  const password = args.join(' ');
+  if (password.length < 12) {
+    console.error('Password must be at least 12 characters.');
+    process.exit(1);
+  }
+
+  console.log(await bcrypt.hash(password, BCRYPT_COST));
+}
+

package/src/cli/help.mjs

@@ -0,0 +1,153 @@
+/**
+ * total-recall help
+ *
+ * Interactive local offline help system.
+ * Queries local specifications, SSSS layout, and command reference files.
+ *
+ * Usage:
+ *   npx total-recall help <command|topic>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.join(__dirname, '..', '..');
+
+export default async function run(argv) {
+  const args = argv || [];
+  const topic = args[0] ? args[0].toLowerCase() : null;
+  const isJson = args.includes('--json') || args.includes('-j');
+
+  const cliRefPath = path.join(ROOT, 'docs', 'reference', 'cli-reference.md');
+  const ssssPath = path.join(ROOT, 'docs', 'SSSS.md');
+  const archPath = path.join(ROOT, 'docs', 'ARCHITECTURE.md');
+
+  if (!fs.existsSync(cliRefPath)) {
+    console.error('  ❌ Error: Total Recall CLI reference docs not found.');
+    process.exit(1);
+  }
+
+  const cliRefContent = fs.readFileSync(cliRefPath, 'utf8');
+
+  if (!topic) {
+    if (isJson) {
+      console.log(JSON.stringify({
+        description: "Total Recall Sovereign OS Help System",
+        command_documentation_path: cliRefPath,
+        available_sections: ["architecture", "ssss", "commands"]
+      }, null, 2));
+      return;
+    }
+    // Print general guide with gorgeous formatting
+    printGeneralHelp();
+    return;
+  }
+
+  // Handle Architecture or SSSS topics
+  if (topic === 'architecture' || topic === 'arch') {
+    if (fs.existsSync(archPath)) {
+      const archContent = fs.readFileSync(archPath, 'utf8');
+      if (isJson) {
+        console.log(JSON.stringify({ topic: 'architecture', content: archContent }, null, 2));
+      } else {
+        console.log(`\n\x1b[35m=== TOTAL RECALL ARCHITECTURE ===\x1b[0m\n`);
+        console.log(archContent.slice(0, 3500) + '\n... (truncated for length)');
+      }
+      return;
+    }
+  }
+
+  if (topic === 'ssss') {
+    if (fs.existsSync(ssssPath)) {
+      const ssssContent = fs.readFileSync(ssssPath, 'utf8');
+      if (isJson) {
+        console.log(JSON.stringify({ topic: 'ssss', content: ssssContent }, null, 2));
+      } else {
+        console.log(`\n\x1b[36m=== STRUCTURED SEMANTIC SYNTAX SYSTEM (SSSS) ===\x1b[0m\n`);
+        console.log(ssssContent.slice(0, 3500) + '\n... (truncated for length)');
+      }
+      return;
+    }
+  }
+
+  // Handle Config, Settings, or Environment topics
+  if (topic === 'config' || topic === 'settings' || topic === 'environment' || topic === 'env') {
+    const configSectionIdx = cliRefContent.indexOf('## Configuration & Environment Variables Reference');
+    if (configSectionIdx !== -1) {
+      const configContent = cliRefContent.slice(configSectionIdx);
+      if (isJson) {
+        console.log(JSON.stringify({ topic: 'config', content: configContent }, null, 2));
+      } else {
+        console.log(`\n\x1b[33m=== TOTAL RECALL CONFIGURATION & SETTINGS ===\x1b[0m\n`);
+        console.log(configContent.trim());
+        console.log('\n' + '─'.repeat(60) + '\n');
+      }
+      return;
+    }
+  }
+
+  // Parse command-specific help from cli-reference.md
+  // Header pattern: ### `command` or ### command
+  const sections = cliRefContent.split(/\n(?=### )/);
+  let matchedSection = null;
+
+  for (const section of sections) {
+    const lines = section.trim().split('\n');
+    const header = lines[0] || '';
+    // Extract command name from e.g. "### `connect`" or "### connect"
+    const cmdMatch = header.match(/###\s+`?([a-zA-Z0-9_-]+)`?/);
+    if (cmdMatch && cmdMatch[1].toLowerCase() === topic) {
+      matchedSection = section;
+      break;
+    }
+  }
+
+  if (matchedSection) {
+    if (isJson) {
+      console.log(JSON.stringify({
+        topic,
+        documentation: matchedSection
+      }, null, 2));
+    } else {
+      console.log(`\n\x1b[32m=== Help: total-recall ${topic} ===\x1b[0m\n`);
+      // Beautify header-less lines
+      const displayContent = matchedSection
+        .replace(/^###\s+.*$/m, '')
+        .trim();
+      console.log(displayContent);
+      console.log('\n' + '─'.repeat(60) + '\n');
+    }
+  } else {
+    console.error(`  ❌ Error: No help section found for topic or command: "${topic}"`);
+    console.error(`  Run 'npx total-recall help' to see the complete list of commands.`);
+    process.exit(1);
+  }
+}
+
+function printGeneralHelp() {
+  console.log(`
+  \x1b[1m\x1b[35m┌─────────────────────────────────────────────────────────┐\x1b[0m
+  \x1b[1m\x1b[35m│  Total Recall Interactive Help System                   │\x1b[0m
+  \x1b[1m\x1b[35m│  query local system documentation and architecture      │\x1b[0m
+  \x1b[1m\x1b[35m└─────────────────────────────────────────────────────────┘\x1b[0m
+
+  \x1b[1mUsage:\x1b[0m
+    npx total-recall help <command>       Get detailed help on a specific subcommand
+    npx total-recall help architecture    View total-recall system & directory architecture
+    npx total-recall help ssss            View SSSS formatting & semantics rules
+    npx total-recall help settings        View comprehensive configuration & environment settings
+
+  \x1b[1mExamples:\x1b[0m
+    npx total-recall help connect
+    npx total-recall help settings
+    npx total-recall help architecture
+
+  \x1b[1mAll Commands Available:\x1b[0m
+    \x1b[33minit\x1b[0m, \x1b[33msetup\x1b[0m, \x1b[33mstart\x1b[0m, \x1b[33mdeploy\x1b[0m, \x1b[33mdoctor\x1b[0m, \x1b[33mdream\x1b[0m, \x1b[33mlint\x1b[0m, \x1b[33mdaemon\x1b[0m, \x1b[33mbackup\x1b[0m, \x1b[33mrestore\x1b[0m, \x1b[33msync\x1b[0m, \x1b[33mstatus\x1b[0m,
+    \x1b[33mgenerate-pat\x1b[0m, \x1b[33mhash-password\x1b[0m, \x1b[33mreset-password\x1b[0m, \x1b[33mcompile\x1b[0m, \x1b[33mrebuild\x1b[0m, \x1b[33msnapshot\x1b[0m, \x1b[33mmigrate\x1b[0m,
+    \x1b[33mimport\x1b[0m, \x1b[33mingest\x1b[0m, \x1b[33mconnect\x1b[0m, \x1b[33mrelay\x1b[0m, \x1b[33muninstall\x1b[0m, \x1b[33mchat\x1b[0m, \x1b[33mremember\x1b[0m, \x1b[33mrecall\x1b[0m, \x1b[33mresearch\x1b[0m, \x1b[33mmap\x1b[0m, \x1b[33mbrain\x1b[0m, \x1b[33mskill\x1b[0m
+`);
+}