@fuzeelogik/myflo 1.0.0-rc.4

package/lib/notes-cmd.js

@@ -0,0 +1,110 @@
+// `flo notes` — quick capture wrapper over memory store. Defaults to the
+// `notes` namespace and auto-derives tags from #hashtags and trailing
+// "tags: a,b,c" lines so notes stay searchable without ceremony.
+
+import { storeEntry, listEntries, searchEntries } from './memory-store.js';
+
+export async function notesCommand(args) {
+  const [sub = 'help', ...rest] = args;
+  if (sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
+  if (sub === 'list') return listCmd(rest);
+  if (sub === 'search') return searchCmd(rest);
+  // Default: treat all args as note text
+  return addCmd(args);
+}
+
+function printHelp() {
+  console.log(`flo notes — quick markdown capture wrapped over flo memory
+
+Usage:
+  flo notes <text>                  Capture a note in ~/.flo/memory/notes.jsonl
+  flo notes "Body with #hashtag and trailing tags:"
+  flo notes list [--limit N] [--json]
+  flo notes search <query> [--limit N] [--json]
+
+Auto-tagging:
+  - Inline #hashtags are extracted as tags
+  - Trailing 'tags: a, b, c' line is parsed and merged
+  - Always tagged 'note'
+
+Notes live in the 'notes' namespace; cross-namespace search via 'flo memory'.
+`);
+}
+
+function parseFlags(args) {
+  const out = { positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--limit') out.limit = Number(args[++i]);
+    else if (a === '--json') out.json = true;
+    else if (a === '--key') out.key = args[++i];
+    else if (a === '--tags') out.extraTags = (args[++i] || '').split(',').map(t => t.trim()).filter(Boolean);
+    else if (!a.startsWith('--')) out.positional.push(a);
+  }
+  return out;
+}
+
+function deriveTags(text) {
+  const tags = new Set(['note']);
+  // #hashtags
+  for (const m of text.matchAll(/#([a-zA-Z0-9_-]+)/g)) {
+    tags.add(m[1].toLowerCase());
+  }
+  // trailing "tags: a, b" line
+  const trailing = text.match(/^tags:\s*(.+)$/im);
+  if (trailing) {
+    for (const t of trailing[1].split(',')) {
+      const v = t.trim().replace(/^["']|["']$/g, '');
+      if (v) tags.add(v.toLowerCase());
+    }
+  }
+  return [...tags];
+}
+
+async function addCmd(args) {
+  const opts = parseFlags(args);
+  const text = opts.positional.join(' ').trim();
+  if (!text) {
+    console.error(`flo notes: missing <text>`);
+    console.error(`Usage: flo notes "<text>"  (use 'flo notes help' for more)`);
+    process.exit(2);
+  }
+  const tags = deriveTags(text);
+  if (opts.extraTags) for (const t of opts.extraTags) if (!tags.includes(t)) tags.push(t);
+  const entry = await storeEntry({
+    namespace: 'notes',
+    key: opts.key || null,
+    value: text,
+    tags,
+    metadata: { capturedAt: new Date().toISOString() },
+  });
+  if (opts.json) console.log(JSON.stringify(entry));
+  else console.log(`flo notes: ${entry.id} (${text.length} chars, tags: ${tags.join(', ')})`);
+}
+
+async function listCmd(args) {
+  const opts = parseFlags(args);
+  const entries = await listEntries({ namespace: 'notes', limit: opts.limit || 50 });
+  if (opts.json) { console.log(JSON.stringify(entries, null, 2)); return; }
+  if (!entries.length) { console.log(`flo notes: nothing yet`); return; }
+  for (const e of entries) {
+    const head = e.value.split('\n')[0].slice(0, 70);
+    console.log(`${e.createdAt.slice(0, 19).replace('T', ' ')}  ${e.id}  ${head}${e.value.length > 70 ? '…' : ''}`);
+  }
+}
+
+async function searchCmd(args) {
+  const opts = parseFlags(args);
+  const query = opts.positional.join(' ');
+  if (!query) {
+    console.error(`flo notes search: missing query`);
+    process.exit(2);
+  }
+  const results = await searchEntries({ namespace: 'notes', query, limit: opts.limit || 20 });
+  if (opts.json) { console.log(JSON.stringify(results, null, 2)); return; }
+  if (!results.length) { console.log(`flo notes search: 0 results`); return; }
+  for (const r of results) {
+    const head = r.value.split('\n')[0].slice(0, 70);
+    console.log(`[${r._score}] ${r.id}  ${head}${r.value.length > 70 ? '…' : ''}`);
+  }
+}

package/lib/replace-ruflo.js

@@ -0,0 +1,133 @@
+// `flo replace ruflo` — cutover script.
+// Removes ruflo / claude-flow entries from ~/.claude/mcp.json and project
+// .claude/settings.json mcpServers blocks, leaving only flo. Idempotent.
+// Backs up both files before writing.
+
+import { readFile, writeFile, copyFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const USER_MCP = join(homedir(), '.claude', 'mcp.json');
+const PROJECT_SETTINGS = join(process.cwd(), '.claude', 'settings.json');
+
+const RUFLO_KEYS = ['ruflo', 'claude-flow'];
+
+export async function replaceCommand(args) {
+  const opts = parseFlags(args);
+  if (opts.help) return printHelp();
+  if (opts.positional[0] && opts.positional[0] !== 'ruflo') {
+    console.error(`flo replace: only 'ruflo' is supported (got '${opts.positional[0]}')`);
+    process.exit(2);
+  }
+
+  console.log(`flo replace ruflo — removing ruflo / claude-flow MCP entries`);
+  console.log('');
+
+  const targets = [
+    { label: 'user-global', path: USER_MCP },
+    { label: 'project', path: PROJECT_SETTINGS },
+  ];
+
+  for (const { label, path } of targets) {
+    if (!existsSync(path)) {
+      console.log(`- ${label}: ${path} not present, skipping`);
+      continue;
+    }
+    let raw, parsed;
+    try {
+      raw = await readFile(path, 'utf8');
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      console.log(`× ${label}: failed to parse ${path}: ${err.message}`);
+      continue;
+    }
+    const result = removeRufloFrom(parsed);
+    if (!result.changed) {
+      console.log(`= ${label}: no ruflo entries found in ${path}`);
+      continue;
+    }
+    if (opts.dryRun) {
+      console.log(`# ${label}: would remove keys ${result.removed.join(', ')} from ${path}`);
+      continue;
+    }
+    const backup = `${path}.flo-bak.${Date.now()}`;
+    await copyFile(path, backup);
+    await writeFile(path, JSON.stringify(parsed, null, 2) + '\n', 'utf8');
+    console.log(`✓ ${label}: removed [${result.removed.join(', ')}] from ${path} (backup: ${backup})`);
+  }
+
+  console.log('');
+  console.log('Done. Restart Claude Code to pick up the change.');
+  console.log("If you need to roll back, the .flo-bak.* file is your snapshot.");
+}
+
+function removeRufloFrom(obj) {
+  const removed = [];
+  // mcpServers block
+  if (obj.mcpServers && typeof obj.mcpServers === 'object') {
+    for (const k of Object.keys(obj.mcpServers)) {
+      const val = obj.mcpServers[k];
+      const args = (val && val.args) ? val.args.join(' ') : '';
+      const cmd = val ? `${val.command || ''} ${args}` : '';
+      if (RUFLO_KEYS.includes(k) || /ruflo|claude-flow/.test(cmd)) {
+        delete obj.mcpServers[k];
+        removed.push(`mcpServers.${k}`);
+      }
+    }
+  }
+  // enabledMcpjsonServers array
+  if (Array.isArray(obj.enabledMcpjsonServers)) {
+    const before = obj.enabledMcpjsonServers.length;
+    obj.enabledMcpjsonServers = obj.enabledMcpjsonServers.filter((s) => !RUFLO_KEYS.includes(s));
+    if (obj.enabledMcpjsonServers.length < before) {
+      removed.push(`enabledMcpjsonServers (${before - obj.enabledMcpjsonServers.length} entries)`);
+    }
+  }
+  // permissions.allow — strip mcp__claude-flow__* / mcp__ruflo__*
+  if (obj.permissions && Array.isArray(obj.permissions.allow)) {
+    const before = obj.permissions.allow.length;
+    obj.permissions.allow = obj.permissions.allow.filter(
+      (entry) => !/mcp__(claude-flow|ruflo)/.test(entry)
+    );
+    if (obj.permissions.allow.length < before) {
+      removed.push(`permissions.allow (${before - obj.permissions.allow.length} entries)`);
+    }
+  }
+  return { changed: removed.length > 0, removed };
+}
+
+function printHelp() {
+  console.log(`flo replace ruflo — cutover from ruflo MCP server to flo
+
+Usage:
+  flo replace ruflo [--dry-run]
+
+Removes ruflo / claude-flow entries from:
+  ~/.claude/mcp.json                       (user-global MCP servers)
+  ./.claude/settings.json                  (project mcpServers + permissions)
+
+Specifically removes:
+  - mcpServers.{ruflo,claude-flow}
+  - mcpServers.* whose command/args contain 'ruflo' or 'claude-flow'
+  - enabledMcpjsonServers entries that match
+  - permissions.allow entries matching 'mcp__ruflo__*' or 'mcp__claude-flow__*'
+
+Both files are backed up to <path>.flo-bak.<ts> before being rewritten.
+
+Idempotent. Re-running on a clean config is a no-op.
+
+This complements 'flo migrate', which only ADDED the flo entry. Run that first
+to register flo, then 'flo replace ruflo' to remove the old server entry.
+`);
+}
+
+function parseFlags(args) {
+  const out = { positional: [] };
+  for (const a of args) {
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (!a.startsWith('--')) out.positional.push(a);
+  }
+  return out;
+}

package/lib/sessions.js

@@ -0,0 +1,82 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const DEFAULT_DIR = '.claude/checkpoints';
+
+export async function sessionsList(args) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    console.log(`flo sessions list — list Claude Code checkpoints
+
+Usage:
+  flo sessions list [--dir <path>] [--limit <n>] [--json]
+
+Options:
+  --dir <path>    Checkpoints directory (default: ${DEFAULT_DIR}).
+  --limit <n>     Max checkpoints to show (default: 25).
+  --json          Output JSON.
+  -h, --help      Show this help.
+`);
+    return;
+  }
+  const records = await readCheckpoints(parsed.dir, parsed.limit);
+  if (parsed.json) {
+    console.log(JSON.stringify(records, null, 2));
+    return;
+  }
+  if (!records.length) {
+    console.log(`flo sessions: no checkpoints found in ${parsed.dir}`);
+    return;
+  }
+  console.log(`tag                                  type        file`);
+  console.log(`-----------------------------------  ----------  ----`);
+  for (const r of records) {
+    const tag = (r.tag || '(no-tag)').padEnd(36).slice(0, 36);
+    const type = (r.type || '').padEnd(10).slice(0, 10);
+    console.log(`${tag}  ${type}  ${r.file || ''}`);
+  }
+  console.log(`\n${records.length} checkpoint(s).`);
+}
+
+export async function readCheckpoints(dir = DEFAULT_DIR, limit = 25) {
+  const fullDir = resolve(dir);
+  if (!existsSync(fullDir)) return [];
+  const entries = await readdir(fullDir);
+  const records = [];
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    const path = join(fullDir, name);
+    try {
+      const raw = await readFile(path, 'utf8');
+      const parsed = JSON.parse(raw);
+      const st = await stat(path);
+      records.push({
+        id: name.replace(/\.json$/, ''),
+        path,
+        mtime: st.mtimeMs,
+        tag: parsed.tag,
+        timestamp: parsed.timestamp,
+        type: parsed.type,
+        file: parsed.file,
+        branch: parsed.branch,
+      });
+    } catch {
+      // skip malformed
+    }
+  }
+  records.sort((a, b) => (b.mtime || 0) - (a.mtime || 0));
+  return records.slice(0, limit);
+}
+
+function parseArgs(args) {
+  const out = { help: false, dir: DEFAULT_DIR, limit: 25, json: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--dir') out.dir = args[++i];
+    else if (a === '--limit') out.limit = Number(args[++i]);
+    else if (a === '--json') out.json = true;
+  }
+  return out;
+}

package/lib/setup.js

@@ -0,0 +1,93 @@
+// `flo setup` — single-command onboarding.
+// Creates ~/.flo home, registers flo as an MCP server, runs doctor, prints next steps.
+// Idempotent. Safe to re-run.
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { migrate } from './migrate.js';
+import { doctor } from './doctor.js';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+
+export async function setupCommand(args) {
+  const opts = parseArgs(args);
+  if (opts.help) return printHelp();
+
+  console.log(`flo setup — onboarding for ${FLO_HOME}`);
+  console.log('');
+
+  // 1. Ensure ~/.flo exists with the expected subtree
+  const dirs = ['memory', 'messages', 'logs'];
+  await mkdir(FLO_HOME, { recursive: true });
+  for (const d of dirs) await mkdir(join(FLO_HOME, d), { recursive: true });
+  console.log(`✓ ~/.flo/ created (memory, messages, logs)`);
+
+  // 2. Touch registry files so they're discoverable from day one
+  for (const f of ['inboxes.json', 'terminals.json']) {
+    const path = join(FLO_HOME, f);
+    if (!existsSync(path)) {
+      await writeFile(path, JSON.stringify({ version: 1, [f.replace('.json', '')]: [] }, null, 2) + '\n', 'utf8');
+    }
+  }
+  console.log(`✓ ~/.flo/inboxes.json and terminals.json initialized`);
+
+  // 3. Register flo as an MCP server in ~/.claude/mcp.json
+  if (!opts.skipMcp) {
+    try {
+      await migrate(opts.dryRun ? ['--dry-run'] : []);
+      console.log(`✓ MCP server registered at ~/.claude/mcp.json (key: 'flo')`);
+    } catch (err) {
+      console.log(`× MCP registration failed: ${err.message}`);
+    }
+  } else {
+    console.log(`- MCP registration skipped (--skip-mcp)`);
+  }
+
+  // 4. Health check
+  console.log('');
+  console.log('Running flo doctor:');
+  console.log('');
+  try {
+    await doctor([]);
+  } catch { /* doctor exits non-zero on any FAIL; that's informational */ }
+
+  // 5. Print next steps
+  console.log('');
+  console.log('---');
+  console.log('Next steps:');
+  console.log('  flo guidance audit --out ~/Desktop/flo-audit.md   # find capability dupes');
+  console.log('  flo inbox add ~/Downloads/inbox                   # register an inbox');
+  console.log('  flo notes "First note with #flo #setup"           # quick capture');
+  console.log('  flo tasks create "Try the web UI" --tags ui       # persistent task');
+  console.log('  cd web && pnpm dev --port 3030                    # localhost dashboard');
+  console.log('');
+  console.log('Restart Claude Code to pick up the flo MCP server.');
+}
+
+function printHelp() {
+  console.log(`flo setup — single-command onboarding
+
+Usage:
+  flo setup [--skip-mcp] [--dry-run]
+
+Idempotent. Re-running is safe — creates anything missing, leaves the rest.
+Steps:
+  1. Create ~/.flo/{memory,messages,logs}/
+  2. Initialize ~/.flo/{inboxes,terminals}.json
+  3. Register flo as MCP server in ~/.claude/mcp.json
+  4. Run health check
+  5. Print next-step suggestions
+`);
+}
+
+function parseArgs(args) {
+  const out = {};
+  for (const a of args) {
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--skip-mcp') out.skipMcp = true;
+    else if (a === '--dry-run') out.dryRun = true;
+  }
+  return out;
+}

package/lib/swarm.js

@@ -0,0 +1,236 @@
+import { readFile, readdir, appendFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const DEFAULT_DIR = '.swarm';
+const CONSENSUS_FILE = 'consensus.jsonl';
+
+export async function recordVote({ proposal, voter, vote, weight, metadata, dir = DEFAULT_DIR }) {
+  if (!proposal) throw new Error('recordVote: proposal is required');
+  if (!voter) throw new Error('recordVote: voter is required');
+  const fullDir = resolve(dir);
+  if (!existsSync(fullDir)) await mkdir(fullDir, { recursive: true });
+  const event = {
+    proposal: String(proposal),
+    voter: String(voter),
+    vote: String(vote ?? 'yes'),
+    weight: typeof weight === 'number' ? weight : 1,
+    metadata: metadata && typeof metadata === 'object' ? metadata : {},
+    ts: new Date().toISOString(),
+  };
+  await appendFile(join(fullDir, CONSENSUS_FILE), JSON.stringify(event) + '\n', 'utf8');
+  return event;
+}
+
+export async function listVotes({ proposal, dir = DEFAULT_DIR } = {}) {
+  const fullDir = resolve(dir);
+  const path = join(fullDir, CONSENSUS_FILE);
+  if (!existsSync(path)) return [];
+  let raw = '';
+  try { raw = await readFile(path, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (!proposal || row.proposal === proposal) out.push(row);
+    } catch { /* skip */ }
+  }
+  return out.sort((a, b) => (a.ts < b.ts ? 1 : -1));
+}
+
+export async function tallyVotes({ proposal, dir = DEFAULT_DIR }) {
+  const votes = await listVotes({ proposal, dir });
+  const byVoter = new Map();
+  for (const v of votes) byVoter.set(v.voter, v);
+  const final = [...byVoter.values()];
+  const tally = {};
+  let totalWeight = 0;
+  for (const v of final) {
+    tally[v.vote] = (tally[v.vote] || 0) + v.weight;
+    totalWeight += v.weight;
+  }
+  return { proposal, totalVoters: final.length, totalWeight, tally };
+}
+
+export async function readSwarmState(dir = DEFAULT_DIR) {
+  const fullDir = resolve(dir);
+  if (!existsSync(fullDir)) return { available: false, dir: fullDir };
+
+  const state = await safeReadJson(join(fullDir, 'state.json'));
+  const qlearn = await safeReadJson(join(fullDir, 'q-learning-model.json'));
+
+  // Compact q-learning summary — the full qTable can be huge.
+  let qlearnSummary = null;
+  if (qlearn) {
+    const qStates = Object.keys(qlearn.qTable || {});
+    qlearnSummary = {
+      version: qlearn.version,
+      encoderVersion: qlearn.encoderVersion,
+      config: qlearn.config,
+      stats: qlearn.stats,
+      metadata: qlearn.metadata,
+      stateCount: qStates.length,
+      sampleStates: qStates.slice(0, 5).map((s) => ({
+        state: s,
+        visits: qlearn.qTable[s]?.visits ?? 0,
+        topQ: Math.max(...(qlearn.qTable[s]?.qValues || [0])),
+      })),
+    };
+  }
+
+  return {
+    available: true,
+    dir: fullDir,
+    state,
+    qlearn: qlearnSummary,
+  };
+}
+
+async function safeReadJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function swarmCommand(args) {
+  const [sub = 'status', ...rest] = args;
+  if (sub === 'status') return swarmStatusCommand(rest);
+  if (sub === 'vote') return swarmVoteCommand(rest);
+  if (sub === 'tally') return swarmTallyCommand(rest);
+  if (sub === 'votes') return swarmVotesCommand(rest);
+  if (sub === 'help' || sub === '--help' || sub === '-h') return printSwarmHelp();
+  console.error(`flo swarm: unknown subcommand '${sub}'`);
+  console.error(`Available: status, vote, tally, votes, help`);
+  process.exit(2);
+}
+
+function printSwarmHelp() {
+  console.log(`flo swarm — coordination + lightweight consensus
+
+Usage:
+  flo swarm status [--dir <path>] [--json]
+  flo swarm vote <proposal> --voter <id> [--vote yes|no|abstain] [--weight N] [--json]
+  flo swarm tally <proposal> [--json]
+  flo swarm votes [<proposal>] [--json]
+
+State files under .swarm/ in the current project:
+  state.json            — populated by 'npx ruflo swarm init' (read-only here)
+  q-learning-model.json — read-only
+  consensus.jsonl       — append-only votes (last vote per voter wins)
+`);
+}
+
+async function swarmVoteCommand(args) {
+  let proposal, voter, vote = 'yes', weight, json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--voter') voter = args[++i];
+    else if (a === '--vote') vote = args[++i];
+    else if (a === '--weight') weight = Number(args[++i]);
+    else if (a === '--json') json = true;
+    else if (!a.startsWith('--') && !proposal) proposal = a;
+  }
+  if (!proposal) { console.error(`flo swarm vote: missing <proposal>`); process.exit(2); }
+  if (!voter) { console.error(`flo swarm vote: missing --voter <id>`); process.exit(2); }
+  const event = await recordVote({ proposal, voter, vote, weight });
+  if (json) console.log(JSON.stringify(event));
+  else console.log(`flo swarm vote: ${voter} voted '${vote}' on '${proposal}' (weight ${event.weight})`);
+}
+
+async function swarmTallyCommand(args) {
+  let proposal, json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') json = true;
+    else if (!a.startsWith('--') && !proposal) proposal = a;
+  }
+  if (!proposal) { console.error(`flo swarm tally: missing <proposal>`); process.exit(2); }
+  const result = await tallyVotes({ proposal });
+  if (json) console.log(JSON.stringify(result));
+  else {
+    console.log(`flo swarm tally for '${proposal}':`);
+    console.log(`  voters: ${result.totalVoters}, total weight: ${result.totalWeight}`);
+    for (const [vote, weight] of Object.entries(result.tally)) {
+      console.log(`  ${vote}: ${weight}`);
+    }
+  }
+}
+
+async function swarmVotesCommand(args) {
+  let proposal, json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') json = true;
+    else if (!a.startsWith('--') && !proposal) proposal = a;
+  }
+  const votes = await listVotes({ proposal });
+  if (json) { console.log(JSON.stringify(votes, null, 2)); return; }
+  if (!votes.length) { console.log(`flo swarm votes: none${proposal ? ' for ' + proposal : ''}`); return; }
+  console.log(`when                 proposal              voter            vote    weight`);
+  console.log(`-------------------  --------------------  ---------------  ------  ------`);
+  for (const v of votes) {
+    const when = v.ts.replace('T', ' ').slice(0, 19);
+    const p = v.proposal.padEnd(20).slice(0, 20);
+    const voter = v.voter.padEnd(15).slice(0, 15);
+    const vote = v.vote.padEnd(6).slice(0, 6);
+    console.log(`${when}  ${p}  ${voter}  ${vote}  ${v.weight}`);
+  }
+}
+
+export async function swarmStatusCommand(args) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    console.log(`flo swarm status — read .swarm/ state
+
+Usage:
+  flo swarm status [--dir <path>] [--json]
+`);
+    return;
+  }
+  const result = await readSwarmState(parsed.dir);
+  if (parsed.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (!result.available) {
+    console.log(`flo swarm: no .swarm/ directory at ${result.dir}`);
+    return;
+  }
+  console.log(`flo swarm status: ${result.dir}`);
+  if (result.state) {
+    console.log(`  id:        ${result.state.swarmId}`);
+    console.log(`  objective: ${result.state.objective}`);
+    console.log(`  strategy:  ${result.state.strategy}`);
+    console.log(`  status:    ${result.state.status}`);
+    console.log(`  agents:    ${result.state.agents}`);
+    if (result.state.agentPlan?.length) {
+      console.log(`  plan:`);
+      for (const p of result.state.agentPlan) {
+        console.log(`    - ${p.count}× ${p.role} (${p.type}): ${p.purpose}`);
+      }
+    }
+  }
+  if (result.qlearn) {
+    console.log(`  q-learning:`);
+    console.log(`    states:   ${result.qlearn.stateCount}`);
+    console.log(`    steps:    ${result.qlearn.stats?.stepCount ?? 0}`);
+    console.log(`    epsilon:  ${result.qlearn.stats?.epsilon?.toFixed(4) ?? '—'}`);
+    console.log(`    avg TD:   ${result.qlearn.stats?.avgTDError?.toFixed(4) ?? '—'}`);
+  }
+}
+
+function parseArgs(args) {
+  const out = { help: false, dir: DEFAULT_DIR, json: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--dir') out.dir = args[++i];
+    else if (a === '--json') out.json = true;
+  }
+  return out;
+}