@jaimevalasek/aioson 1.6.0 → 1.7.0

package/src/commands/hooks-install.js

@@ -0,0 +1,347 @@
+'use strict';
+
+/**
+ * aioson hooks:install [projectDir] --agent=<name> --tool=<claude|antigravity|codex|all>
+ *
+ * Installs AIOSON event hooks into the AI tool's settings file.
+ * After installation, every Write/Edit/Bash tool call and session stop
+ * automatically emits a runtime event to SQLite — no manual aioson calls needed.
+ *
+ * Supported tools:
+ *   --tool=claude      → ~/.claude/settings.json
+ *   --tool=antigravity → ~/.gemini/antigravity/hooks.json  (+ .agents/hooks.json in project)
+ *   --tool=codex       → ~/.codex/config.yaml  (limited: no hook system, documents workaround)
+ *   --tool=all         → installs for all detected tools
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+
+const HOME = os.homedir();
+
+// ─── Config file paths ────────────────────────────────────────────────────────
+
+const CONFIG_PATHS = {
+  claude: path.join(HOME, '.claude', 'settings.json'),
+  antigravity: path.join(HOME, '.gemini', 'antigravity', 'hooks.json'),
+  antigravity_workspace: '.agents/hooks.json' // relative to project
+};
+
+// ─── Hook command templates ───────────────────────────────────────────────────
+
+function makeEmitCommand(agentName, source) {
+  // $PWD is the project directory at hook execution time
+  return `aioson hooks:emit "$PWD" --agent=${agentName} --source=${source} 2>/dev/null || true`;
+}
+
+function makeDoneCommand(agentName) {
+  return `aioson agent:done "$PWD" --agent=${agentName} --summary="Session ended via ${agentName} hook" 2>/dev/null || true`;
+}
+
+// ─── Claude Code ─────────────────────────────────────────────────────────────
+
+function buildClaudeHooks(agentName) {
+  const emitCmd = makeEmitCommand(agentName, 'claude');
+  const doneCmd = makeDoneCommand(agentName);
+
+  return {
+    PostToolUse: [
+      {
+        matcher: 'Write|Edit|MultiEdit',
+        hooks: [{ type: 'command', command: emitCmd }]
+      },
+      {
+        matcher: 'Bash',
+        hooks: [{ type: 'command', command: emitCmd }]
+      },
+      {
+        matcher: 'Task|TodoWrite',
+        hooks: [{ type: 'command', command: emitCmd }]
+      }
+    ],
+    Stop: [
+      {
+        hooks: [{ type: 'command', command: doneCmd }]
+      }
+    ]
+  };
+}
+
+async function installClaudeHooks(agentName, dryRun, logger) {
+  const configPath = CONFIG_PATHS.claude;
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+
+  let existing = {};
+  try {
+    existing = JSON.parse(await fs.readFile(configPath, 'utf8'));
+  } catch { /* file doesn't exist yet */ }
+
+  const newHooks = buildClaudeHooks(agentName);
+
+  // Merge: add AIOSON hooks without removing existing ones
+  const merged = { ...existing };
+  if (!merged.hooks) merged.hooks = {};
+
+  for (const [event, hookList] of Object.entries(newHooks)) {
+    if (!merged.hooks[event]) {
+      merged.hooks[event] = hookList;
+    } else {
+      // Remove any existing AIOSON hooks (to avoid duplicates on reinstall)
+      const filtered = merged.hooks[event].filter((entry) => {
+        const cmd = entry.hooks?.[0]?.command || '';
+        return !cmd.includes('aioson hooks:emit') && !cmd.includes('aioson agent:done');
+      });
+      merged.hooks[event] = [...filtered, ...hookList];
+    }
+  }
+
+  if (!dryRun) {
+    await fs.writeFile(configPath, JSON.stringify(merged, null, 2), 'utf8');
+    logger.log(`  ✓ Claude Code — ${configPath}`);
+  } else {
+    logger.log(`  [dry-run] Would write: ${configPath}`);
+    logger.log(`  Hooks to add:`);
+    logger.log(`    PostToolUse (Write|Edit|MultiEdit|Bash|Task|TodoWrite) → hooks:emit`);
+    logger.log(`    Stop → agent:done`);
+  }
+
+  return { tool: 'claude', configPath, hooks: newHooks };
+}
+
+// ─── Antigravity ─────────────────────────────────────────────────────────────
+
+function buildAntigravityHooks(agentName) {
+  const emitCmd = makeEmitCommand(agentName, 'antigravity');
+  const doneCmd = makeDoneCommand(agentName);
+  const startCmd = `aioson live:start "$PWD" --agent=${agentName} --tool=antigravity --no-launch 2>/dev/null || true`;
+
+  return {
+    SessionStart: [{ type: 'command', command: startCmd }],
+    PostToolUse: [
+      { matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: emitCmd }] },
+      { matcher: 'Bash', hooks: [{ type: 'command', command: emitCmd }] },
+      { matcher: 'Task|TodoWrite', hooks: [{ type: 'command', command: emitCmd }] }
+    ],
+    SessionEnd: [{ type: 'command', command: doneCmd }],
+    Stop: [{ type: 'command', command: doneCmd }]
+  };
+}
+
+async function installAntigravityHooks(agentName, projectDir, dryRun, logger) {
+  const globalPath = CONFIG_PATHS.antigravity;
+  const workspacePath = path.join(projectDir, CONFIG_PATHS.antigravity_workspace);
+
+  const hooks = buildAntigravityHooks(agentName);
+
+  if (!dryRun) {
+    await fs.mkdir(path.dirname(globalPath), { recursive: true });
+    await fs.mkdir(path.dirname(workspacePath), { recursive: true });
+
+    // Global hooks
+    let globalExisting = {};
+    try { globalExisting = JSON.parse(await fs.readFile(globalPath, 'utf8')); } catch { /* new file */ }
+    const mergedGlobal = mergeAntigravityHooks(globalExisting, hooks);
+    await fs.writeFile(globalPath, JSON.stringify(mergedGlobal, null, 2), 'utf8');
+    logger.log(`  ✓ Antigravity global — ${globalPath}`);
+
+    // Workspace hooks (project-scoped, takes priority)
+    let wsExisting = {};
+    try { wsExisting = JSON.parse(await fs.readFile(workspacePath, 'utf8')); } catch { /* new file */ }
+    const mergedWs = mergeAntigravityHooks(wsExisting, hooks);
+    await fs.writeFile(workspacePath, JSON.stringify(mergedWs, null, 2), 'utf8');
+    logger.log(`  ✓ Antigravity workspace — ${workspacePath}`);
+  } else {
+    logger.log(`  [dry-run] Would write: ${globalPath}`);
+    logger.log(`  [dry-run] Would write: ${workspacePath}`);
+    logger.log(`  Hooks to add: SessionStart → live:start, PostToolUse → hooks:emit, SessionEnd/Stop → agent:done`);
+  }
+
+  return { tool: 'antigravity', globalPath, workspacePath, hooks };
+}
+
+function mergeAntigravityHooks(existing, newHooks) {
+  const merged = { ...existing };
+  if (!merged.hooks) merged.hooks = {};
+
+  for (const [event, entries] of Object.entries(newHooks)) {
+    const existingEntries = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+    // Remove previous AIOSON entries
+    const filtered = existingEntries.filter((e) => {
+      const cmd = (e.command || e.hooks?.[0]?.command || '');
+      return !cmd.includes('aioson');
+    });
+    const newEntries = Array.isArray(entries) ? entries : [entries];
+    merged.hooks[event] = [...filtered, ...newEntries];
+  }
+
+  return merged;
+}
+
+// ─── Codex (OpenAI) ───────────────────────────────────────────────────────────
+
+async function installCodexHooks(agentName, dryRun, logger) {
+  // Codex CLI does not have a native hook system as of 2026.
+  // The workaround: add a shell alias that wraps `codex` and calls live:start before / agent:done after.
+  const configPath = path.join(HOME, '.codex', 'config.yaml');
+  const wrapperPath = path.join(HOME, '.codex', 'aioson-wrapper.sh');
+
+  const wrapperScript = `#!/bin/bash
+# AIOSON session wrapper for Codex CLI
+# Generated by: aioson hooks:install --tool=codex --agent=${agentName}
+# Usage: replace \`codex\` calls with \`codex-aioson\` OR add to .bashrc:
+#   alias codex='${wrapperPath}'
+
+PROJECT_DIR="\${1:-$PWD}"
+AGENT="${agentName}"
+
+# Start live session before Codex runs
+aioson live:start "$PROJECT_DIR" --agent="$AGENT" --tool=codex --no-launch 2>/dev/null || true
+
+# Run Codex with all original arguments
+codex-bin "$@"
+EXIT_CODE=$?
+
+# Register session end
+aioson agent:done "$PROJECT_DIR" --agent="$AGENT" --summary="Codex session ended" 2>/dev/null || true
+
+exit $EXIT_CODE
+`;
+
+  if (!dryRun) {
+    await fs.mkdir(path.dirname(wrapperPath), { recursive: true });
+    await fs.writeFile(wrapperPath, wrapperScript, 'utf8');
+    await fs.chmod(wrapperPath, 0o755);
+    logger.log(`  ✓ Codex wrapper — ${wrapperPath}`);
+    logger.log(`  ⚠ Codex has no native hooks. Add this to ~/.bashrc:`);
+    logger.log(`    alias codex='${wrapperPath}'`);
+    logger.log(`  Or rename: mv $(which codex) $(which codex)-bin`);
+  } else {
+    logger.log(`  [dry-run] Would write: ${wrapperPath}`);
+    logger.log(`  ⚠ Codex has no native hook system. Wrapper script approach only.`);
+  }
+
+  return { tool: 'codex', wrapperPath, limited: true };
+}
+
+// ─── Detection ───────────────────────────────────────────────────────────────
+
+async function detectInstalledTools() {
+  const detected = [];
+  const checks = [
+    { tool: 'claude', path: path.join(HOME, '.claude') },
+    { tool: 'antigravity', path: path.join(HOME, '.gemini', 'antigravity') },
+    { tool: 'codex', path: path.join(HOME, '.codex') }
+  ];
+
+  for (const { tool, path: p } of checks) {
+    try {
+      await fs.access(p);
+      detected.push(tool);
+    } catch { /* not installed */ }
+  }
+
+  return detected;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function runHooksInstall({ args, options = {}, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  const dryRun = options['dry-run'] || options.dryRun || false;
+  let tool = options.tool ? String(options.tool).trim().toLowerCase() : 'all';
+
+  if (tool === 'all') {
+    const detected = await detectInstalledTools();
+    if (detected.length === 0) {
+      logger.log('No supported AI tools detected. Install Claude Code, Antigravity, or Codex first.');
+      return { ok: false, reason: 'no_tools_detected' };
+    }
+    logger.log(`Detected tools: ${detected.join(', ')}`);
+    tool = detected.join(',');
+  }
+
+  const tools = tool.split(',').map((t) => t.trim()).filter(Boolean);
+  const results = [];
+
+  logger.log(`Hooks Install — agent: @${agentName}${dryRun ? ' [dry-run]' : ''}`);
+  logger.log('─'.repeat(50));
+
+  for (const t of tools) {
+    try {
+      if (t === 'claude') {
+        results.push(await installClaudeHooks(agentName, dryRun, logger));
+      } else if (t === 'antigravity') {
+        results.push(await installAntigravityHooks(agentName, projectDir, dryRun, logger));
+      } else if (t === 'codex') {
+        results.push(await installCodexHooks(agentName, dryRun, logger));
+      } else {
+        logger.log(`  ⚠ Unknown tool: ${t} — supported: claude, antigravity, codex`);
+      }
+    } catch (err) {
+      logger.log(`  ✗ ${t}: ${err.message}`);
+      results.push({ tool: t, error: err.message });
+    }
+  }
+
+  logger.log('─'.repeat(50));
+
+  if (!dryRun) {
+    logger.log('');
+    logger.log('Hooks installed. From now on:');
+    logger.log('  • Every file write/edit → logged as artifact event');
+    logger.log('  • Every bash command → logged as step_done event');
+    logger.log('  • Session end → logged as agent:done');
+    logger.log('');
+    logger.log('To verify: aioson live:status . --agent=' + agentName);
+    logger.log('To uninstall: aioson hooks:uninstall --tool=' + tools.join(','));
+  }
+
+  if (options.json) {
+    return { ok: true, results, agentName, dryRun };
+  }
+
+  return { ok: true, results, agentName, dryRun };
+}
+
+async function runHooksUninstall({ args, options = {}, logger }) {
+  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  const dryRun = options['dry-run'] || options.dryRun || false;
+  const tool = options.tool ? String(options.tool).trim().toLowerCase() : 'claude';
+  const tools = tool.split(',').map((t) => t.trim()).filter(Boolean);
+
+  logger.log(`Hooks Uninstall — agent: @${agentName}${dryRun ? ' [dry-run]' : ''}`);
+  logger.log('─'.repeat(50));
+
+  for (const t of tools) {
+    if (t === 'claude') {
+      try {
+        const configPath = CONFIG_PATHS.claude;
+        const existing = JSON.parse(await fs.readFile(configPath, 'utf8'));
+        if (existing.hooks) {
+          for (const event of Object.keys(existing.hooks)) {
+            existing.hooks[event] = (existing.hooks[event] || []).filter((entry) => {
+              const cmd = entry.hooks?.[0]?.command || entry.command || '';
+              return !cmd.includes('aioson hooks:emit') && !cmd.includes('aioson agent:done') && !cmd.includes('aioson live:start');
+            });
+            if (existing.hooks[event].length === 0) delete existing.hooks[event];
+          }
+          if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
+        }
+        if (!dryRun) {
+          await fs.writeFile(configPath, JSON.stringify(existing, null, 2), 'utf8');
+          logger.log(`  ✓ Claude Code hooks removed — ${configPath}`);
+        } else {
+          logger.log(`  [dry-run] Would remove AIOSON hooks from: ${configPath}`);
+        }
+      } catch {
+        logger.log(`  Claude Code settings not found — nothing to remove`);
+      }
+    }
+  }
+
+  return { ok: true };
+}
+
+module.exports = { runHooksInstall, runHooksUninstall };

package/src/commands/learning-auto-promote.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * aioson learning:auto-promote — auto-promote frequent learnings to rules files.
+ *
+ * Scans project_learnings with frequency >= threshold and promotes eligible ones
+ * to .aioson/rules/. Domain learnings (not promotable to universal rules) are noted
+ * but not written. No LLM calls.
+ *
+ * Usage:
+ *   aioson learning:auto-promote .
+ *   aioson learning:auto-promote . --threshold=3
+ *   aioson learning:auto-promote . --threshold=2 --dry-run
+ *   aioson learning:auto-promote . --json
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb, listProjectLearnings } = require('../runtime-store');
+
+const DEFAULT_THRESHOLD = 3;
+const RULES_DIR = '.aioson/rules';
+const BAR = '━'.repeat(30);
+
+// Only 'process' and 'quality' type learnings become universal rules.
+// 'domain' learnings are project-specific and should not become global rules.
+// 'preference' learnings go to project.context.md (handled by learning:evolve).
+const PROMOTABLE_TYPES = new Set(['process', 'quality']);
+
+function slugify(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50);
+}
+
+function buildRuleContent(learning) {
+  const confidence = learning.confidence === 'high' ? ' (high confidence)' : learning.confidence === 'low' ? ' (low confidence)' : '';
+  const lines = [
+    '---',
+    `title: ${learning.title}`,
+    `type: ${learning.type}`,
+    `frequency: ${learning.frequency}`,
+    `source: auto-promoted`,
+    'agents: all',
+    '---',
+    '',
+    `# ${learning.title}${confidence}`,
+    ''
+  ];
+
+  if (learning.evidence) {
+    lines.push(`> ${learning.evidence}`, '');
+  }
+
+  if (learning.type === 'process') {
+    lines.push('**When:** During any implementation or workflow session.');
+    lines.push(`**Rule:** ${learning.title}`);
+  } else if (learning.type === 'quality') {
+    lines.push('**When:** Before committing or delivering a deliverable.');
+    lines.push(`**Rule:** ${learning.title}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function runLearningAutoPromote({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const threshold = options.threshold ? parseInt(options.threshold) : DEFAULT_THRESHOLD;
+  const dryRun = Boolean(options['dry-run'] || options.dry);
+
+  if (isNaN(threshold) || threshold < 1) {
+    if (options.json) return { ok: false, reason: 'invalid_threshold' };
+    logger.log('--threshold must be a positive integer (default: 3)');
+    return { ok: false };
+  }
+
+  const handle = await openRuntimeDb(targetDir, { mustExist: true });
+  if (!handle) {
+    if (options.json) return { ok: false, reason: 'no_runtime', message: 'No runtime database found. Run aioson runtime:init first.' };
+    logger.log('No runtime database found. Run aioson runtime:init first.');
+    return { ok: false };
+  }
+
+  let learnings;
+  try {
+    learnings = listProjectLearnings(handle.db, 'active');
+  } finally {
+    handle.db.close();
+  }
+
+  // Filter by threshold
+  const eligible = learnings.filter((l) => Number(l.frequency || 1) >= threshold);
+
+  if (!options.json) {
+    logger.log('');
+    logger.log('Learning Auto-Promotion');
+    logger.log(BAR);
+    logger.log(`Scanning project_learnings (frequency ≥ ${threshold}):`);
+    logger.log('');
+  }
+
+  const promoted = [];
+  const noted = [];
+  const skipped = [];
+
+  for (const learning of eligible) {
+    if (!PROMOTABLE_TYPES.has(learning.type)) {
+      noted.push({
+        title: learning.title,
+        type: learning.type,
+        frequency: learning.frequency,
+        reason: `${learning.type} learning — not promotable to universal rule`
+      });
+      continue;
+    }
+
+    const slug = slugify(learning.title);
+    const fileName = `process-${slug}.md`;
+    const filePath = path.join(targetDir, RULES_DIR, fileName);
+
+    // Check if already exists
+    let alreadyExists = false;
+    try {
+      await fs.access(filePath);
+      alreadyExists = true;
+    } catch { /* ok */ }
+
+    if (alreadyExists) {
+      skipped.push({ title: learning.title, file: fileName, reason: 'already exists' });
+      continue;
+    }
+
+    const content = buildRuleContent(learning);
+
+    if (!dryRun) {
+      await fs.mkdir(path.join(targetDir, RULES_DIR), { recursive: true });
+      await fs.writeFile(filePath, content, 'utf8');
+    }
+
+    promoted.push({
+      learning_id: learning.learning_id,
+      title: learning.title,
+      type: learning.type,
+      frequency: learning.frequency,
+      file: path.join(RULES_DIR, fileName)
+    });
+  }
+
+  const result = {
+    ok: true,
+    threshold,
+    dry_run: dryRun,
+    eligible: eligible.length,
+    promoted: promoted.length,
+    noted: noted.length,
+    skipped: skipped.length,
+    promoted_items: promoted,
+    noted_items: noted,
+    skipped_items: skipped
+  };
+
+  if (options.json) return result;
+
+  // Human output
+  for (const p of promoted) {
+    const dryStr = dryRun ? ' (dry-run)' : '';
+    logger.log(`  ✓ "${p.title}" (freq: ${p.frequency}) → promoted to ${p.file}${dryStr}`);
+  }
+
+  for (const n of noted) {
+    logger.log(`  ○ "${n.title}" (freq: ${n.frequency}) → ${n.reason}`);
+  }
+
+  for (const s of skipped) {
+    logger.log(`  — "${s.title}" → ${s.reason}`);
+  }
+
+  logger.log('');
+  if (promoted.length > 0) {
+    logger.log(`${promoted.length} rule${promoted.length !== 1 ? 's' : ''} ${dryRun ? 'would be' : ''} created.`);
+    if (!dryRun) logger.log('Run: aioson learning:evolve to apply to agent genomes.');
+  } else if (eligible.length === 0) {
+    logger.log(`No learnings with frequency ≥ ${threshold} found.`);
+  } else {
+    logger.log('No new rules to create.');
+  }
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runLearningAutoPromote };

package/src/commands/learning-evolve.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
+const { randomUUID } = require('node:crypto');
 const { openRuntimeDb, listSquadLearnings, listProjectLearnings, promoteSquadLearning, promoteProjectLearning } = require('../runtime-store');
 
 const AGENTS_DIR = path.join('.aioson', 'agents');
@@ -265,17 +266,25 @@ async function applyProposed(proposed, projectDir, db, logger, quiet, squadSlug)
       if (!quiet) logger.log(`  ✓ Aplicado: ${delta.file} (+${delta.count} learnings)`);
     }
 
-    // Registra no log de evolução
+    // Registra no evolution-log.jsonl (5.5: per-delta entries with UUIDs for rollback)
     const evolutionDir = path.resolve(projectDir, EVOLUTION_DIR);
     await fs.mkdir(evolutionDir, { recursive: true });
-    const logFile = path.join(evolutionDir, 'log.jsonl');
-    const logEntry = JSON.stringify({
-      appliedAt: new Date().toISOString(),
-      deltasCount: evolved,
-      squad: squadSlug || null,
-      files: proposed.map((d) => d.file)
-    });
-    await fs.appendFile(logFile, `${logEntry}\n`, 'utf8');
+    const perDeltaLogFile = path.join(evolutionDir, 'evolution-log.jsonl');
+    const ts = new Date().toISOString();
+    for (const delta of proposed.slice(0, evolved)) {
+      const logEntry = JSON.stringify({
+        id: randomUUID(),
+        ts,
+        type: 'append',
+        file: delta.file,
+        section: delta.section || null,
+        content: delta.content,
+        learning_ids: delta.sourceIds || [],
+        squad: squadSlug || null,
+        status: 'applied'
+      });
+      await fs.appendFile(perDeltaLogFile, `${logEntry}\n`, 'utf8');
+    }
 
     if (!quiet) logger.log(`\n${evolved} delta(s) aplicado(s) com sucesso.`);
   } finally {

package/src/commands/learning-export.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'learning';
+}
+
+function buildNodeContent(learning) {
+  const id = slugify(`${learning.type}-${learning.title}`);
+  const now = new Date().toISOString().slice(0, 10);
+  return {
+    id,
+    content: `---
+id: ${id}
+type: ${learning.type}
+title: ${learning.title}
+frequency: ${learning.frequency || 1}
+last_reinforced: ${learning.last_reinforced ? learning.last_reinforced.slice(0, 10) : now}
+source_feature: ${learning.feature_slug || 'project'}
+promoted_to: null
+created_at: ${learning.created_at ? learning.created_at.slice(0, 10) : now}
+---
+
+# ${learning.title}
+
+**Evidence:** ${learning.evidence || `Detected in ${learning.frequency || 1} session(s).`}
+
+## Applications
+- Review and apply this learning in future sessions of type: ${learning.type}
+
+## Links
+<!-- Add cross-references here -->
+`
+  };
+}
+
+async function runLearningExport({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const minFrequency = Number(options['min-frequency'] || options.minFrequency || 1);
+  const brainsDir = path.join(targetDir, '.aioson', 'brains');
+
+  const { db, dbPath } = await openRuntimeDb(targetDir, { mustExist: true });
+
+  if (!db) {
+    if (!options.json) logger.log('No runtime database found.');
+    return { ok: false, reason: 'no_db' };
+  }
+
+  try {
+    const learnings = db.prepare(`
+      SELECT learning_id, feature_slug, type, title, frequency, last_reinforced,
+             evidence, source_session, created_at
+      FROM project_learnings
+      WHERE status = 'active' AND frequency >= ?
+      ORDER BY frequency DESC, updated_at DESC
+    `).all(minFrequency);
+
+    if (learnings.length === 0) {
+      if (!options.json) logger.log(`No learnings with frequency >= ${minFrequency}.`);
+      return { ok: true, exported: 0, dbPath };
+    }
+
+    await fs.mkdir(brainsDir, { recursive: true });
+
+    const exported = [];
+    for (const learning of learnings) {
+      const { id, content } = buildNodeContent(learning);
+      const filePath = path.join(brainsDir, `${id}.md`);
+      await fs.writeFile(filePath, content, 'utf8');
+      exported.push({ id, filePath, frequency: learning.frequency });
+    }
+
+    const promotable = learnings.filter((l) => l.frequency >= 5).length;
+
+    if (options.json) {
+      return { ok: true, exported: exported.length, nodes: exported, promotable, dbPath };
+    }
+
+    logger.log(`Learning Export — min-frequency: ${minFrequency}`);
+    logger.log('─'.repeat(50));
+    for (const { id, frequency } of exported) {
+      logger.log(`  ${id}.md ✓ (frequency: ${frequency})`);
+    }
+    logger.log('─'.repeat(50));
+    logger.log(`${exported.length} nodes written to .aioson/brains/`);
+    if (promotable > 0) {
+      logger.log(`${promotable} learning(s) with frequency ≥ 5 — run: aioson learning:evolve to promote to genome`);
+    }
+
+    return { ok: true, exported: exported.length, nodes: exported, promotable, dbPath };
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { runLearningExport };