serpentstack 0.2.11 → 0.2.13

package/bin/serpentstack.js

@@ -68,9 +68,12 @@ function showHelp() {
   divider('Any project');
   console.log(`    ${cyan('skills')}                        Download all skills + persistent agent configs`);
   console.log(`    ${cyan('skills update')}                 Update base skills to latest versions`);
-  console.log(`    ${cyan('persistent')}                    Manage and launch persistent background agents`);
+  console.log(`    ${cyan('persistent')}                    Status dashboard (first run = full setup)`);
+  console.log(`    ${cyan('persistent')} ${dim('--configure')}       Edit project settings`);
+  console.log(`    ${cyan('persistent')} ${dim('--agents')}          Change agent models, enable/disable`);
+  console.log(`    ${cyan('persistent')} ${dim('--models')}          List installed & recommended models`);
+  console.log(`    ${cyan('persistent')} ${dim('--start')}           Launch enabled agents`);
   console.log(`    ${cyan('persistent')} ${dim('--stop')}            Stop all running agents`);
-  console.log(`    ${cyan('persistent')} ${dim('--reconfigure')}     Change models, enable/disable agents`);
   console.log();
 
   divider('Options');
@@ -134,7 +137,13 @@ async function main() {
     }
   } else if (noun === 'persistent') {
     const { persistent } = await import('../lib/commands/persistent.js');
-    await persistent({ stop: !!flags.stop, reconfigure: !!flags.reconfigure });
+    await persistent({
+      stop: !!flags.stop,
+      configure: !!flags.configure,
+      agents: !!flags.agents,
+      start: !!flags.start,
+      models: !!flags.models,
+    });
   } else {
     error(`Unknown command: ${bold(noun)}`);
     const suggestion = suggestCommand(noun);

package/lib/commands/persistent.js

@@ -3,7 +3,7 @@ import { join, resolve } from 'node:path';
 import { execFile, spawn } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
-import { info, success, warn, error, bold, dim, green, cyan, yellow, red, divider, printBox, printHeader } from '../utils/ui.js';
+import { info, success, warn, error, bold, dim, green, cyan, yellow, red, divider, printBox, printHeader, spinner } from '../utils/ui.js';
 import {
   parseAgentMd,
   discoverAgents,
@@ -47,12 +47,139 @@ async function askYesNo(rl, label, defaultYes = true) {
   return val === 'y' || val === 'yes';
 }
 
+// ─── Preflight ──────────────────────────────────────────────
+
+/**
+ * Check all prerequisites and return a status object.
+ * Exits the process with helpful guidance if anything critical is missing.
+ */
+async function preflight(projectDir) {
+  const soulPath = join(projectDir, '.openclaw/SOUL.md');
+
+  // Check for .openclaw workspace
+  if (!existsSync(soulPath)) {
+    error('No .openclaw/ workspace found.');
+    console.log();
+    console.log(`  ${dim('Run')} ${bold('serpentstack skills')} ${dim('first to download skills and agent configs.')}`);
+    console.log();
+    process.exit(1);
+  }
+
+  // Check for agent definitions
+  const agentDirs = discoverAgents(projectDir);
+  if (agentDirs.length === 0) {
+    error('No agents found in .openclaw/agents/');
+    console.log();
+    console.log(`  ${dim('Run')} ${bold('serpentstack skills')} ${dim('to download the default agents,')}`);
+    console.log(`  ${dim('or create your own at')} ${bold('.openclaw/agents/<name>/AGENT.md')}`);
+    console.log();
+    process.exit(1);
+  }
+
+  // Parse agent definitions
+  const parsed = [];
+  for (const agent of agentDirs) {
+    try {
+      const agentMd = parseAgentMd(agent.agentMdPath);
+      parsed.push({ ...agent, agentMd });
+    } catch (err) {
+      warn(`Skipping ${bold(agent.name)}: ${err.message}`);
+    }
+  }
+  if (parsed.length === 0) {
+    error('No valid AGENT.md files found.');
+    console.log();
+    process.exit(1);
+  }
+
+  // Detect runtime dependencies in parallel
+  const spin = spinner('Checking runtime...');
+  const [hasOpenClaw, available] = await Promise.all([
+    which('openclaw'),
+    detectModels(),
+  ]);
+  spin.stop();
+
+  return { soulPath, parsed, hasOpenClaw, available };
+}
+
+/**
+ * Print a summary of what's installed and what's missing.
+ * Returns true if everything needed to launch is present.
+ */
+function printPreflightStatus(hasOpenClaw, available) {
+  divider('Runtime');
+  console.log();
+
+  // OpenClaw
+  if (hasOpenClaw) {
+    console.log(`    ${green('✓')} OpenClaw ${dim('— persistent agent runtime')}`);
+  } else {
+    console.log(`    ${red('✗')} OpenClaw ${dim('— not installed')}`);
+  }
+
+  // Ollama
+  if (available.ollamaRunning) {
+    console.log(`    ${green('✓')} Ollama  ${dim(`— running, ${available.local.length} model(s) installed`)}`);
+  } else if (available.ollamaInstalled) {
+    console.log(`    ${yellow('△')} Ollama  ${dim('— installed but not running')}`);
+  } else {
+    console.log(`    ${yellow('○')} Ollama  ${dim('— not installed (optional, for free local models)')}`);
+  }
+
+  // API key
+  if (available.hasApiKey) {
+    console.log(`    ${green('✓')} API key ${dim('— configured for cloud models')}`);
+  }
+
+  console.log();
+
+  // Actionable guidance for missing pieces
+  const issues = [];
+
+  if (!hasOpenClaw) {
+    issues.push({
+      label: 'Install OpenClaw (required to run agents)',
+      cmd: 'npm install -g openclaw@latest',
+    });
+  }
+
+  if (!available.ollamaInstalled) {
+    issues.push({
+      label: 'Install Ollama for free local models (recommended)',
+      cmd: 'curl -fsSL https://ollama.com/install.sh | sh',
+    });
+  } else if (!available.ollamaRunning) {
+    issues.push({
+      label: 'Start Ollama',
+      cmd: 'ollama serve',
+    });
+  }
+
+  if (available.ollamaRunning && available.local.length === 0) {
+    issues.push({
+      label: 'Pull a model (Ollama is running but has no models)',
+      cmd: 'ollama pull llama3.2',
+    });
+  }
+
+  if (issues.length > 0) {
+    for (const issue of issues) {
+      console.log(`  ${dim(issue.label + ':')}`);
+      console.log(`    ${dim('$')} ${bold(issue.cmd)}`);
+      console.log();
+    }
+  }
+
+  return hasOpenClaw;
+}
+
 // ─── Model Picker ───────────────────────────────────────────
 
 async function pickModel(rl, agentName, currentModel, available) {
   const choices = [];
 
-  // Local models first (free, fast, recommended)
+  // Local models first
   if (available.local.length > 0) {
     console.log(`    ${dim('── Local')} ${green('free')} ${dim('──────────────────────')}`);
     for (const m of available.local) {
@@ -65,12 +192,12 @@ async function pickModel(rl, agentName, currentModel, available) {
       const params = m.params ? dim(` ${m.params}`) : '';
       const quant = m.quant ? dim(` ${m.quant}`) : '';
       const size = m.size ? dim(` (${m.size})`) : '';
-      const tag = isCurrent ? green(' \u2190 current') : '';
+      const tag = isCurrent ? green(' ← current') : '';
       console.log(`  ${marker} ${num} ${label}${params}${quant}${size}${tag}`);
     }
   }
 
-  // Cloud models (require API key, cost money)
+  // Cloud models
   if (available.cloud.length > 0) {
     const apiNote = available.hasApiKey ? green('key ✓') : yellow('needs API key');
     console.log(`    ${dim('── Cloud')} ${apiNote} ${dim('─────────────────────')}`);
@@ -82,15 +209,20 @@ async function pickModel(rl, agentName, currentModel, available) {
       const num = dim(`${idx + 1}.`);
       const label = isCurrent ? bold(m.name) : m.name;
       const provider = m.provider ? dim(` (${m.provider})`) : '';
-      const tag = isCurrent ? green(' \u2190 current') : '';
+      const tag = isCurrent ? green(' ← current') : '';
       console.log(`  ${marker} ${num} ${label}${provider}${tag}`);
     }
   }
 
+  if (choices.length === 0) {
+    warn('No models available. Install Ollama and pull a model first.');
+    console.log(`    ${dim('$')} ${bold('ollama pull llama3.2')}`);
+    return currentModel;
+  }
+
   // If current model isn't in either list, add it
   if (!choices.some(c => c.id === currentModel)) {
     choices.unshift({ id: currentModel, name: modelShortName(currentModel), tier: 'custom' });
-    // Re-render isn't needed since we'll just note it
     console.log(`    ${dim(`Current: ${modelShortName(currentModel)} (not in detected models)`)}`);
   }
 
@@ -102,9 +234,8 @@ async function pickModel(rl, agentName, currentModel, available) {
 
   const selected = (idx >= 0 && idx < choices.length) ? choices[idx] : choices[Math.max(0, currentIdx)];
 
-  // Warn about cloud model costs
   if (selected.tier === 'cloud' && available.local.length > 0) {
-    warn(`Cloud models cost tokens per heartbeat cycle. Consider a local model for persistent agents.`);
+    warn(`Cloud models cost tokens per heartbeat. Consider a local model for persistent agents.`);
   }
   if (selected.tier === 'cloud' && !available.hasApiKey) {
     warn(`No API key detected. Run ${bold('openclaw configure')} to set up authentication.`);
@@ -157,9 +288,7 @@ end tell`;
       try {
         const child = spawn(bin, args, { stdio: 'ignore', detached: true });
         child.unref();
-        // Verify it didn't immediately fail
-        const alive = child.pid && !child.killed;
-        if (alive) return bin;
+        if (child.pid && !child.killed) return bin;
       } catch { continue; }
     }
   }
@@ -197,7 +326,6 @@ function stopAllAgents(projectDir) {
     } catch (err) {
       if (err.code === 'ESRCH') {
         removePid(projectDir, name);
-        // Don't count already-dead processes as "stopped"
       } else {
         error(`Failed to stop ${bold(name)}: ${err.message}`);
       }
@@ -235,124 +363,85 @@ function printAgentLine(name, agentMd, config, statusInfo) {
   }
 }
 
-// ─── Main Flow ──────────────────────────────────────────────
-
-export async function persistent({ stop = false, reconfigure = false } = {}) {
-  const projectDir = process.cwd();
-
-  printHeader();
-
-  // ── Stop ──
-  if (stop) {
-    stopAllAgents(projectDir);
-    return;
-  }
-
-  // ── Preflight checks ──
-  const soulPath = join(projectDir, '.openclaw/SOUL.md');
-  if (!existsSync(soulPath)) {
-    error('No .openclaw/ workspace found.');
-    console.log(`  Run ${bold('serpentstack skills')} first to download the workspace files.`);
-    console.log();
-    process.exit(1);
-  }
+function printStatusDashboard(config, parsed, projectDir) {
+  console.log(`  ${bold(config.project.name)} ${dim(`— ${config.project.framework}`)}`);
+  console.log(`  ${dim(`Dev: ${config.project.devCmd} · Test: ${config.project.testCmd}`)}`);
+  console.log();
 
-  const agents = discoverAgents(projectDir);
-  if (agents.length === 0) {
-    error('No agents found in .openclaw/agents/');
-    console.log(`  Run ${bold('serpentstack skills')} to download the default agents,`);
-    console.log(`  or create your own at ${bold('.openclaw/agents/<name>/AGENT.md')}`);
-    console.log();
-    process.exit(1);
+  divider('Agents');
+  console.log();
+  for (const { name, agentMd } of parsed) {
+    const statusInfo = getAgentStatus(projectDir, name, config);
+    printAgentLine(name, agentMd, config, statusInfo);
   }
+  console.log();
+}
 
-  // Check OpenClaw early — don't waste time configuring if it's missing
-  const hasOpenClaw = await which('openclaw');
-  if (!hasOpenClaw) {
-    warn('OpenClaw is not installed.');
-    console.log();
-    console.log(`  ${dim('OpenClaw is the persistent agent runtime.')}`);
-    console.log(`  ${dim('Install it first, then re-run this command:')}`);
-    console.log();
-    console.log(`  ${dim('$')} ${bold('npm install -g openclaw@latest')}`);
-    console.log(`  ${dim('$')} ${bold('serpentstack persistent')}`);
-    console.log();
-    process.exit(1);
-  }
+// ─── Models Command ─────────────────────────────────────────
 
-  cleanStalePids(projectDir);
+async function runModels(available) {
+  divider('Installed Models');
+  console.log();
 
-  // Parse agent definitions
-  const parsed = [];
-  for (const agent of agents) {
-    try {
-      const agentMd = parseAgentMd(agent.agentMdPath);
-      parsed.push({ ...agent, agentMd });
-    } catch (err) {
-      warn(`Skipping ${bold(agent.name)}: ${err.message}`);
+  if (available.local.length > 0) {
+    for (const m of available.local) {
+      const params = m.params ? dim(` ${m.params}`) : '';
+      const quant = m.quant ? dim(` ${m.quant}`) : '';
+      const size = m.size ? dim(` (${m.size})`) : '';
+      console.log(`    ${green('●')} ${bold(m.name)}${params}${quant}${size}`);
     }
+  } else {
+    console.log(`    ${dim('No local models installed.')}`);
   }
-  if (parsed.length === 0) {
-    error('No valid AGENT.md files found.');
+
+  if (available.cloud.length > 0) {
     console.log();
-    process.exit(1);
+    const apiNote = available.hasApiKey ? green('key ✓') : yellow('needs API key');
+    console.log(`  ${dim('Cloud models')} ${apiNote}`);
+    for (const m of available.cloud) {
+      console.log(`    ${dim('●')} ${m.name} ${dim(`(${m.provider})`)}`);
+    }
   }
 
-  // Load config
-  let config = readConfig(projectDir) || { project: {}, agents: {} };
-  const needsSetup = !config.project?.name || reconfigure;
-
-  // Detect models in background while we show status
-  const modelsPromise = detectModels();
+  console.log();
 
-  // ── If configured, show status dashboard ──
-  if (!needsSetup) {
-    console.log(`  ${bold(config.project.name)} ${dim(`— ${config.project.framework}`)}`);
-    console.log(`  ${dim(`Dev: ${config.project.devCmd} · Test: ${config.project.testCmd}`)}`);
+  // Show recommended models to install
+  if (available.recommended.length > 0) {
+    divider('Recommended Models');
     console.log();
-
-    for (const { name, agentMd } of parsed) {
-      const statusInfo = getAgentStatus(projectDir, name, config);
-      printAgentLine(name, agentMd, config, statusInfo);
+    if (available.recommendedLive) {
+      success(`Fetched latest models from ${cyan('ollama.com/library')}`);
+    } else {
+      warn(`Could not reach ollama.com — showing cached recommendations`);
     }
     console.log();
-
-    // Determine what to do
-    const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
-    const runningNames = new Set(listPids(projectDir).map(p => p.name));
-    const startable = enabledAgents.filter(a => !runningNames.has(a.name));
-
-    if (startable.length === 0 && runningNames.size > 0) {
-      info('All enabled agents are running.');
-      console.log(`  ${dim('Run')} ${bold('serpentstack persistent --stop')} ${dim('to stop them.')}`);
-      console.log(`  ${dim('Run')} ${bold('serpentstack persistent --reconfigure')} ${dim('to change settings.')}`);
-      console.log();
-      return;
-    }
-
-    if (startable.length === 0) {
-      info('No agents are enabled.');
-      console.log(`  ${dim('Run')} ${bold('serpentstack persistent --reconfigure')} ${dim('to enable agents.')}`);
-      console.log();
-      return;
+    for (const r of available.recommended) {
+      console.log(`    ${dim('$')} ${bold(`ollama pull ${r.name}`)}  ${dim(`${r.params} — ${r.description}`)}`);
     }
-
-    // Start startable agents
-    await launchAgents(projectDir, startable, config, soulPath);
-    return;
+    console.log();
   }
 
-  // ── First-time setup / reconfigure ──
-  if (reconfigure) {
-    info('Reconfiguring...');
+  // Status summary
+  if (!available.ollamaInstalled) {
+    console.log(`  ${dim('Install Ollama for free local models:')}`);
+    console.log(`    ${dim('$')} ${bold('curl -fsSL https://ollama.com/install.sh | sh')}`);
+    console.log();
+  } else if (!available.ollamaRunning) {
+    console.log(`  ${dim('Start Ollama to use local models:')}`);
+    console.log(`    ${dim('$')} ${bold('ollama serve')}`);
     console.log();
   }
 
+  console.log(`  ${dim('Browse all models:')} ${cyan('https://ollama.com/library')}`);
+  console.log();
+}
+
+// ─── Configure Flow ─────────────────────────────────────────
+
+async function runConfigure(projectDir, config, soulPath) {
   const rl = createInterface({ input: stdin, output: stdout });
-  let configDirty = false;
 
   try {
-    // ── Project configuration ──
     const detected = detectProjectDefaults(projectDir);
     const template = detectTemplateDefaults(projectDir);
     const existing = config.project || {};
@@ -382,13 +471,12 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
       testCmd: await ask(rl, 'Test command', defaults.testCmd),
       conventions: await ask(rl, 'Key conventions', defaults.conventions),
     };
-    configDirty = true;
 
     // Update SOUL.md
     if (existsSync(soulPath)) {
       let soul = readFileSync(soulPath, 'utf8');
       const ctx = [
-        `# ${config.project.name} \u2014 Persistent Development Agents`,
+        `# ${config.project.name} — Persistent Development Agents`,
         '',
         `**Project:** ${config.project.name}`,
         `**Language:** ${config.project.language}`,
@@ -405,25 +493,26 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
     console.log();
     success(`Updated ${bold('.openclaw/SOUL.md')}`);
     console.log();
+  } finally {
+    rl.close();
+  }
 
-    // ── Agent configuration ──
-    const available = await modelsPromise;
+  config._configured = true;
+  writeConfig(projectDir, config);
+  success(`Saved ${bold('.openclaw/config.json')}`);
+  console.log();
+}
 
-    if (available.local.length > 0) {
-      info(`${available.local.length} local model(s) detected via Ollama`);
-    } else {
-      warn('No local models found. Install Ollama and pull a model for free persistent agents:');
-      console.log(`  ${dim('$')} ${bold('ollama pull llama3.2')}`);
-    }
-    if (available.hasApiKey) {
-      info('API key configured for cloud models');
-    }
-    console.log();
+// ─── Agents Flow ────────────────────────────────────────────
 
-    divider('Agents');
-    console.log(`  ${dim('Enable/disable each agent and pick a model.')}`);
-    console.log();
+async function runAgents(projectDir, config, parsed, available) {
+  divider('Agents');
+  console.log(`  ${dim('Enable/disable each agent and pick a model.')}`);
+  console.log();
+
+  const rl = createInterface({ input: stdin, output: stdout });
 
+  try {
     for (const { name, agentMd } of parsed) {
       const existingAgent = config.agents?.[name];
       const currentEnabled = existingAgent?.enabled !== false;
@@ -443,43 +532,49 @@ export async function persistent({ stop = false, reconfigure = false } = {}) {
 
       config.agents[name] = { enabled, model };
 
-      const status = enabled ? green('\u2713 enabled') : dim('\u2717 disabled');
+      const status = enabled ? green('✓ enabled') : dim('✗ disabled');
       const modelLabel = enabled ? `, ${modelShortName(model)}` : '';
       console.log(`    ${status}${modelLabel}`);
       console.log();
     }
-
-    configDirty = true;
   } finally {
     rl.close();
-    // Only save if we completed configuration
-    if (configDirty) {
-      writeConfig(projectDir, config);
-      success(`Saved ${bold('.openclaw/config.json')}`);
-      console.log();
-    }
   }
 
-  // Show status and launch
-  for (const { name, agentMd } of parsed) {
-    const statusInfo = getAgentStatus(projectDir, name, config);
-    printAgentLine(name, agentMd, config, statusInfo);
-  }
+  config._configured = true;
+  writeConfig(projectDir, config);
+  success(`Saved ${bold('.openclaw/config.json')}`);
   console.log();
+}
 
-  const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
-  if (enabledAgents.length === 0) {
-    info('No agents enabled. Run with --reconfigure to enable agents.');
+// ─── Start Flow ─────────────────────────────────────────────
+
+async function runStart(projectDir, parsed, config, soulPath, hasOpenClaw) {
+  if (!hasOpenClaw) {
+    error('Cannot launch agents — OpenClaw is not installed.');
+    console.log();
+    console.log(`  ${dim('$')} ${bold('npm install -g openclaw@latest')}`);
     console.log();
     return;
   }
 
-  await launchAgents(projectDir, enabledAgents, config, soulPath);
-}
+  const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
+  const runningNames = new Set(listPids(projectDir).map(p => p.name));
+  const startable = enabledAgents.filter(a => !runningNames.has(a.name));
 
-// ─── Launch Flow ────────────────────────────────────────────
+  if (startable.length === 0 && runningNames.size > 0) {
+    info('All enabled agents are already running.');
+    console.log();
+    return;
+  }
+
+  if (startable.length === 0) {
+    info('No agents are enabled.');
+    console.log(`  ${dim('Run')} ${bold('serpentstack persistent --agents')} ${dim('to enable agents.')}`);
+    console.log();
+    return;
+  }
 
-async function launchAgents(projectDir, agentsToStart, config, soulPath) {
   const rl = createInterface({ input: stdin, output: stdout });
   const toStart = [];
 
@@ -487,7 +582,7 @@ async function launchAgents(projectDir, agentsToStart, config, soulPath) {
     divider('Launch');
     console.log();
 
-    for (const agent of agentsToStart) {
+    for (const agent of startable) {
       const model = getEffectiveModel(agent.name, agent.agentMd.meta, config);
       const yes = await askYesNo(rl, `Start ${bold(agent.name)} ${dim(`(${modelShortName(model)})`)}?`, true);
       if (yes) toStart.push(agent);
@@ -521,18 +616,14 @@ async function launchAgents(projectDir, agentsToStart, config, soulPath) {
       const absProject = resolve(projectDir);
 
       const openclawCmd = `OPENCLAW_STATE_DIR='${join(absWorkspace, '.state')}' openclaw start --workspace '${absWorkspace}'`;
-
       const method = openInTerminal(`SerpentStack: ${name}`, openclawCmd, absProject);
 
       if (method) {
-        // For terminal-spawned agents, record workspace path so we can track it
-        // The terminal process will create its own PID — we record ours as a marker
-        writePid(projectDir, name, -1); // -1 = terminal-managed
+        writePid(projectDir, name, -1);
         success(`${bold(name)} opened in ${method} ${dim(`(${modelShortName(effectiveModel)})`)}`);
         started++;
       } else {
-        // Fallback: background process
-        warn(`No terminal detected \u2014 starting ${bold(name)} in background`);
+        warn(`No terminal detected — starting ${bold(name)} in background`);
         const child = spawn('openclaw', ['start', '--workspace', absWorkspace], {
           stdio: 'ignore',
           detached: true,
@@ -553,10 +644,126 @@ async function launchAgents(projectDir, agentsToStart, config, soulPath) {
   if (started > 0) {
     success(`${started} agent(s) launched — fangs out 🐍`);
     console.log();
-    printBox('Manage agents', [
-      `${dim('$')} ${bold('serpentstack persistent')}                ${dim('# status + start')}`,
-      `${dim('$')} ${bold('serpentstack persistent --stop')}         ${dim('# stop all')}`,
-      `${dim('$')} ${bold('serpentstack persistent --reconfigure')}  ${dim('# change models')}`,
+  }
+}
+
+// ─── Main Entry Point ───────────────────────────────────────
+
+export async function persistent({ stop = false, configure = false, agents = false, start = false, models = false } = {}) {
+  const projectDir = process.cwd();
+
+  printHeader();
+
+  // ── Stop (doesn't need full preflight) ──
+  if (stop) {
+    cleanStalePids(projectDir);
+    stopAllAgents(projectDir);
+    return;
+  }
+
+  // ── Full preflight (checks workspace, agents, runtime) ──
+  const { soulPath, parsed, hasOpenClaw, available } = await preflight(projectDir);
+  cleanStalePids(projectDir);
+
+  // Load config
+  let config = readConfig(projectDir) || { project: {}, agents: {} };
+  const isConfigured = !!config._configured;
+
+  // ── --models: list installed and recommended models ──
+  if (models) {
+    await runModels(available);
+    return;
+  }
+
+  // ── --configure: edit project settings ──
+  if (configure) {
+    await runConfigure(projectDir, config, soulPath);
+    return;
+  }
+
+  // ── --agents: edit agent models and enabled state ──
+  if (agents) {
+    config = readConfig(projectDir) || config;
+    await runAgents(projectDir, config, parsed, available);
+    return;
+  }
+
+  // ── --start: launch agents ──
+  if (start) {
+    await runStart(projectDir, parsed, config, soulPath, hasOpenClaw);
+    return;
+  }
+
+  // ── Bare `serpentstack persistent` ──
+  if (isConfigured) {
+    // Show dashboard
+    printStatusDashboard(config, parsed, projectDir);
+
+    const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
+    const runningNames = new Set(listPids(projectDir).map(p => p.name));
+    const startable = enabledAgents.filter(a => !runningNames.has(a.name));
+
+    if (startable.length === 0 && runningNames.size > 0) {
+      info('All enabled agents are running.');
+    } else if (startable.length === 0) {
+      info('No agents are enabled.');
+    } else {
+      info(`${startable.length} agent(s) ready to start.`);
+    }
+
+    console.log();
+    printBox('Commands', [
+      `${dim('$')} ${bold('serpentstack persistent --start')}      ${dim('# launch agents')}`,
+      `${dim('$')} ${bold('serpentstack persistent --stop')}       ${dim('# stop all')}`,
+      `${dim('$')} ${bold('serpentstack persistent --configure')}  ${dim('# edit project settings')}`,
+      `${dim('$')} ${bold('serpentstack persistent --agents')}     ${dim('# change models')}`,
+      `${dim('$')} ${bold('serpentstack persistent --models')}     ${dim('# list & install models')}`,
     ]);
+    console.log();
+    return;
+  }
+
+  // ── First-time setup: guided walkthrough ──
+
+  // Step 0: Show runtime status
+  const canLaunch = printPreflightStatus(hasOpenClaw, available);
+
+  if (!canLaunch) {
+    console.log(`  ${dim('Install the missing dependencies above, then run:')}`);
+    console.log(`    ${dim('$')} ${bold('serpentstack persistent')}`);
+    console.log();
+
+    // Still let them configure even without OpenClaw
+    const rl = createInterface({ input: stdin, output: stdout });
+    let proceed;
+    try {
+      proceed = await askYesNo(rl, `Continue with project configuration anyway?`, true);
+    } finally {
+      rl.close();
+    }
+
+    if (!proceed) {
+      console.log();
+      return;
+    }
+    console.log();
+  }
+
+  // Step 1: Project settings
+  await runConfigure(projectDir, config, soulPath);
+  config = readConfig(projectDir) || config;
+
+  // Step 2: Agent settings
+  await runAgents(projectDir, config, parsed, available);
+  config = readConfig(projectDir) || config;
+
+  // Step 3: Launch (only if OpenClaw is installed)
+  if (canLaunch) {
+    await runStart(projectDir, parsed, config, soulPath, hasOpenClaw);
+  } else {
+    console.log();
+    info('Skipping launch — install OpenClaw first, then run:');
+    console.log(`    ${dim('$')} ${bold('serpentstack persistent --start')}`);
+    console.log();
   }
 }

package/lib/commands/skills-init.js

@@ -139,11 +139,10 @@ export async function skillsInit({ force = false } = {}) {
   ]);
 
   printBox('Want persistent background agents too?', [
-    `${dim('$')} ${bold('serpentstack persistent')}`,
+    `${dim('$')} ${bold('serpentstack persistent')}              ${dim('# first-time setup walkthrough')}`,
     '',
-    `${dim('Agents that watch your dev server, run tests, and keep')}`,
-    `${dim('skills fresh — each in its own terminal. Pick which to')}`,
-    `${dim('run and choose local or cloud models.')}`,
+    `${dim('Configures your project, picks models, and launches')}`,
+    `${dim('agents — each in its own terminal window.')}`,
   ]);
   console.log();
 }

package/lib/utils/models.js

@@ -1,43 +1,149 @@
 import { execFile } from 'node:child_process';
 
+// ─── Fallback Recommendations ───────────────────────────────
+// Used only when the Ollama library API is unreachable.
+// When online, we fetch fresh models from ollama.com/api/tags.
+
+const FALLBACK_RECOMMENDATIONS = [
+  { name: 'gemma3:4b',       params: '4B',  size: '8.0 GB',  description: 'Small and fast — great for log watching' },
+  { name: 'ministral-3:3b',  params: '3B',  size: '4.3 GB',  description: 'Lightweight, good for simple tasks' },
+  { name: 'ministral-3:8b',  params: '8B',  size: '9.7 GB',  description: 'Balanced — good default for most agents' },
+  { name: 'devstral-small-2:24b', params: '24B', size: '14.6 GB', description: 'Code-focused, strong for test runner agents' },
+];
+
+// Max model size to recommend (16 GB — fits on most dev machines)
+const MAX_RECOMMEND_SIZE = 16 * 1024 ** 3;
+
 /**
  * Detect all available models: local (Ollama) and cloud (via OpenClaw auth).
- * Local models are preferred for persistent agents — they're free and fast.
- * Cloud models require API keys and cost money per token.
+ * Also fetches recommended models from the Ollama library.
  *
- * Returns { local: [...], cloud: [...], hasApiKey: bool }
+ * Returns {
+ *   local: [...],
+ *   cloud: [...],
+ *   hasApiKey: bool,
+ *   ollamaRunning: bool,
+ *   ollamaInstalled: bool,
+ *   openclawInstalled: bool,
+ *   recommended: [...],  // models user doesn't have yet
+ * }
  */
 export async function detectModels() {
-  const [ollamaModels, openclawInfo] = await Promise.all([
-    detectOllamaModels(),
+  const [ollamaStatus, openclawInfo, libraryResult] = await Promise.all([
+    detectOllamaStatus(),
     detectOpenClawAuth(),
+    fetchOllamaLibrary(),
   ]);
 
+  // Filter out models the user already has installed
+  const installedNames = new Set(ollamaStatus.models.map(m => m.name.split(':')[0]));
+  const recommended = libraryResult.models.filter(r => {
+    const baseName = r.name.split(':')[0];
+    return !installedNames.has(baseName);
+  });
+
   return {
-    local: ollamaModels,
+    local: ollamaStatus.models,
     cloud: openclawInfo.models,
     hasApiKey: openclawInfo.hasApiKey,
+    ollamaRunning: ollamaStatus.running,
+    ollamaInstalled: ollamaStatus.installed,
+    openclawInstalled: openclawInfo.installed,
+    recommended,
+    recommendedLive: libraryResult.live,
   };
 }
 
+// ─── Ollama Library (live from ollama.com) ───────────────────
+
 /**
- * Detect locally installed Ollama models via the REST API.
- * GET http://localhost:11434/api/tags returns structured JSON with real
- * parameter counts, sizes, and quantization levels — no CLI parsing needed.
+ * Fetch available models from the Ollama library API.
+ * Filters to models suitable for persistent agents (< MAX_RECOMMEND_SIZE).
+ * Falls back to a hardcoded list if the API is unreachable.
  */
-async function detectOllamaModels() {
+async function fetchOllamaLibrary() {
+  try {
+    const response = await fetchWithTimeout('https://ollama.com/api/tags', 5000);
+    if (!response.ok) return { models: FALLBACK_RECOMMENDATIONS, live: false };
+
+    const data = await response.json();
+    if (!data.models || !Array.isArray(data.models)) return { models: FALLBACK_RECOMMENDATIONS, live: false };
+
+    // Filter to models that fit on a dev machine
+    const suitable = data.models
+      .filter(m => m.size > 0 && m.size <= MAX_RECOMMEND_SIZE)
+      .sort((a, b) => new Date(b.modified_at) - new Date(a.modified_at))
+      .map(m => {
+        const name = m.name || '';
+        const params = extractParams(name, m.size);
+        return {
+          name,
+          params,
+          size: formatBytes(m.size),
+          description: describeModel(name),
+        };
+      });
+
+    return suitable.length > 0
+      ? { models: suitable, live: true }
+      : { models: FALLBACK_RECOMMENDATIONS, live: false };
+  } catch {
+    return { models: FALLBACK_RECOMMENDATIONS, live: false };
+  }
+}
+
+/**
+ * Generate a short description for a model based on its name.
+ */
+function describeModel(name) {
+  const n = name.toLowerCase();
+  if (n.includes('devstral') || n.includes('codellama') || n.includes('deepseek-coder') || n.includes('coder'))
+    return 'Code-focused';
+  if (n.includes('gemma')) return 'Google, general purpose';
+  if (n.includes('llama')) return 'Meta, general purpose';
+  if (n.includes('mistral') || n.includes('ministral')) return 'Mistral AI';
+  if (n.includes('qwen')) return 'Alibaba, multilingual';
+  if (n.includes('nemotron')) return 'NVIDIA';
+  if (n.includes('gpt-oss')) return 'Open-source GPT variant';
+  return 'General purpose';
+}
+
+/**
+ * Extract parameter count from model name tag or estimate from size.
+ */
+function extractParams(name, size) {
+  // Check for explicit param count in the name (e.g., "gemma3:4b", "ministral-3:8b")
+  const tagMatch = name.match(/:(\d+\.?\d*)([bBmM])/);
+  if (tagMatch) return `${tagMatch[1]}${tagMatch[2].toUpperCase()}`;
+
+  // Estimate from size
+  return guessParamsFromSize(size);
+}
+
+// ─── Ollama Local Status ────────────────────────────────────
+
+async function detectOllamaStatus() {
+  const result = { installed: false, running: false, models: [] };
+
+  try {
+    await execAsync('which', ['ollama']);
+    result.installed = true;
+  } catch {
+    return result;
+  }
+
   try {
     const response = await fetchWithTimeout('http://localhost:11434/api/tags', 3000);
-    if (!response.ok) return [];
+    if (!response.ok) return result;
 
+    result.running = true;
     const data = await response.json();
-    if (!data.models || !Array.isArray(data.models)) return [];
+    if (!data.models || !Array.isArray(data.models)) return result;
 
-    return data.models.map(m => {
+    result.models = data.models.map(m => {
       const name = (m.name || '').replace(':latest', '');
       if (!name) return null;
 
-      // Use the real parameter count from the API when available
       const details = m.details || {};
       const params = formatParamCount(details.parameter_size) || guessParamsFromSize(m.size);
       const quant = details.quantization_level || '';
@@ -53,71 +159,34 @@ async function detectOllamaModels() {
       };
     }).filter(Boolean);
   } catch {
-    // Ollama not running or not installed
-    return [];
+    // Ollama installed but not running
   }
-}
-
-/**
- * Format parameter count from Ollama API (e.g., "7B", "3.2B", "70B").
- * The API returns strings like "7B", "3.21B", etc. in details.parameter_size.
- */
-function formatParamCount(paramSize) {
-  if (!paramSize) return '';
-  // Already formatted like "7B" or "3.2B"
-  const s = String(paramSize).trim();
-  if (/^\d+\.?\d*[BbMm]$/i.test(s)) return s.toUpperCase();
-  return s;
-}
 
-/**
- * Fallback: estimate parameter count from file size.
- * Rough heuristic: ~0.5GB per billion parameters for Q4 quantization.
- */
-function guessParamsFromSize(bytes) {
-  if (!bytes || bytes <= 0) return '';
-  const gb = bytes / (1024 ** 3);
-  const billions = Math.round(gb * 2); // Q4 ≈ 0.5GB/B
-  if (billions > 0) return `~${billions}B`;
-  return '';
-}
-
-/**
- * Format bytes into human-readable size (e.g., "4.7 GB").
- */
-function formatBytes(bytes) {
-  if (!bytes || bytes <= 0) return '';
-  const gb = bytes / (1024 ** 3);
-  if (gb >= 1) return `${gb.toFixed(1)} GB`;
-  const mb = bytes / (1024 ** 2);
-  return `${Math.round(mb)} MB`;
+  return result;
 }
 
-/**
- * Fetch with timeout using AbortController (Node 18+).
- */
-function fetchWithTimeout(url, timeoutMs) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  return fetch(url, { signal: controller.signal }).finally(() => clearTimeout(timeout));
-}
+// ─── OpenClaw Auth & Cloud Models ───────────────────────────
 
-/**
- * Check OpenClaw for configured models and API key status.
- */
 async function detectOpenClawAuth() {
-  const result = { models: [], hasApiKey: false };
+  const result = { models: [], hasApiKey: false, installed: false };
 
   try {
-    // Check if any API key is configured via openclaw models status
-    const status = await execAsync('openclaw', ['models', 'status']);
+    await execAsync('which', ['openclaw']);
+    result.installed = true;
+  } catch {
+    result.models = [
+      { id: 'anthropic/claude-haiku-4-20250414', name: 'Haiku', provider: 'anthropic', tier: 'cloud' },
+      { id: 'anthropic/claude-sonnet-4-20250514', name: 'Sonnet', provider: 'anthropic', tier: 'cloud' },
+    ];
+    return result;
+  }
 
-    // Look for "api_key" or "configured" in the output
+  try {
+    const status = await execAsync('openclaw', ['models', 'status']);
     if (status.includes('api_key') || status.includes('configured')) {
       result.hasApiKey = true;
     }
 
-    // Get the model catalog for cloud options
     const list = await execAsync('openclaw', ['models', 'list', '--json']);
     try {
       const models = JSON.parse(list);
@@ -132,7 +201,6 @@ async function detectOpenClawAuth() {
           }));
       }
     } catch {
-      // Fall back to text parsing
       const text = await execAsync('openclaw', ['models', 'list']);
       const lines = text.trim().split('\n').filter(l => l.trim() && !l.startsWith('Model'));
       result.models = lines.map(l => {
@@ -142,7 +210,6 @@ async function detectOpenClawAuth() {
       }).filter(Boolean);
     }
   } catch {
-    // OpenClaw not installed or no models configured — use defaults
     result.models = [
       { id: 'anthropic/claude-haiku-4-20250414', name: 'Haiku', provider: 'anthropic', tier: 'cloud' },
       { id: 'anthropic/claude-sonnet-4-20250514', name: 'Sonnet', provider: 'anthropic', tier: 'cloud' },
@@ -152,21 +219,49 @@ async function detectOpenClawAuth() {
   return result;
 }
 
+// ─── Formatting Helpers ─────────────────────────────────────
+
+function formatParamCount(paramSize) {
+  if (!paramSize) return '';
+  const s = String(paramSize).trim();
+  if (/^\d+\.?\d*[BbMm]$/i.test(s)) return s.toUpperCase();
+  return s;
+}
+
+function guessParamsFromSize(bytes) {
+  if (!bytes || bytes <= 0) return '';
+  const gb = bytes / (1024 ** 3);
+  const billions = Math.round(gb * 2);
+  if (billions > 0) return `~${billions}B`;
+  return '';
+}
+
+function formatBytes(bytes) {
+  if (!bytes || bytes <= 0) return '';
+  const gb = bytes / (1024 ** 3);
+  if (gb >= 1) return `${gb.toFixed(1)} GB`;
+  const mb = bytes / (1024 ** 2);
+  return `${Math.round(mb)} MB`;
+}
+
+function fetchWithTimeout(url, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  return fetch(url, { signal: controller.signal }).finally(() => clearTimeout(timeout));
+}
+
 /**
  * Short display name for a model ID.
  */
 export function modelShortName(model) {
   if (!model) return 'unknown';
-  // Anthropic models
   if (model.startsWith('anthropic/')) {
     if (model.includes('haiku')) return 'Haiku';
     if (model.includes('sonnet')) return 'Sonnet';
     if (model.includes('opus')) return 'Opus';
     return model.slice('anthropic/'.length);
   }
-  // Ollama models
   if (model.startsWith('ollama/')) return model.slice('ollama/'.length);
-  // Other: strip provider prefix
   if (model.includes('/')) return model.split('/').pop();
   return model;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serpentstack",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "CLI for SerpentStack — AI-driven development standards with project-specific skills and persistent agents",
   "type": "module",
   "bin": {