grimoire-framework 1.0.18 → 1.0.21

package/bin/commands/metrics.js

@@ -1,107 +1,265 @@
 /**
- * Grimoire Metrics CLI Command - Advanced Aggregator
+ * Grimoire Metrics CLI Command — Dashboard + Period Filters + CSV Export
  *
- * Aggregates productivity and usage metrics from daily logs.
+ * grimoire metrics                   # Resumo do mês atual
+ * grimoire metrics --period week     # Últimos 7 dias
+ * grimoire metrics --period month    # Últimos 30 dias
+ * grimoire metrics --period all      # Todo o histórico
+ * grimoire metrics export --csv      # Exporta para CSV
+ * grimoire metrics track <event>     # Registra um evento manualmente
  */
 
+'use strict';
+
 const path = require('path');
 const fs = require('fs/promises');
-const existsSync = require('fs').existsSync;
+const fsSync = require('fs');
 
-/**
- * Run the metrics command
- * @param {string[]} args - Command arguments
- */
+// ── Agent personas catalogue ───────────────────────────────────────────────────
+const AGENT_ICONS = {
+  'dev': '🎨', 'qa': '🖌️', 'architect': '🏛️', 'pm': '📋', 'sm': '🌊',
+  'devops': '⚡', 'data-engineer': '📊', 'analyst': '🔍',
+  'ux-design-expert': '🎭', 'po': '🎯', 'squad-creator': '🗿',
+  'grimoire-master': '👑',
+};
+
+// ── Entry point ────────────────────────────────────────────────────────────────
 async function run(args) {
   let baseDir = process.cwd();
-  if (!existsSync(path.join(baseDir, '.grimoire')) && existsSync(path.join(baseDir, 'grimoire', '.grimoire'))) {
+  if (!fsSync.existsSync(path.join(baseDir, '.grimoire')) &&
+    fsSync.existsSync(path.join(baseDir, 'grimoire', '.grimoire'))) {
     baseDir = path.join(baseDir, 'grimoire');
   }
 
   const metricsDir = path.join(baseDir, '.grimoire', 'metrics');
 
-  if (!existsSync(metricsDir)) {
-    console.error('❌ Metrics system not found.');
-    return;
+  // Auto-create metrics dir if .grimoire exists
+  if (!fsSync.existsSync(metricsDir)) {
+    if (fsSync.existsSync(path.join(baseDir, '.grimoire'))) {
+      await fs.mkdir(path.join(metricsDir, 'daily'), { recursive: true });
+      console.log('✅ Metrics directory initialized at .grimoire/metrics/');
+    } else {
+      console.error('❌ Grimoire not installed. Run: npx grimoire-framework install');
+      return;
+    }
   }
 
+  // Sub-commands
+  const sub = args[0];
+  if (sub === 'export') { await exportMetrics(metricsDir, args.slice(1)); return; }
+  if (sub === 'track') { await trackEvent(metricsDir, args.slice(1)); return; }
+  if (sub === 'help') { showHelp(); return; }
+
+  // Parse period
+  const periodIdx = args.indexOf('--period');
+  const period = periodIdx !== -1 ? args[periodIdx + 1] : 'month';
+
   try {
-    const stats = await aggregateMetrics(metricsDir);
-    showDashboard(stats);
-  } catch (error) {
-    console.error(`❌ Error aggregating metrics: ${error.message}`);
+    const stats = await aggregateMetrics(metricsDir, period);
+    showDashboard(stats, period);
+  } catch (e) {
+    console.error(`❌ Error: ${e.message}`);
   }
 }
 
-async function aggregateMetrics(metricsDir) {
+// ── Period utilities ───────────────────────────────────────────────────────────
+function cutoffDate(period) {
+  const d = new Date();
+  if (period === 'week') d.setDate(d.getDate() - 7);
+  else if (period === 'month') d.setDate(d.getDate() - 30);
+  else if (period === 'all') return new Date(0);
+  else d.setDate(d.getDate() - 30); // default month
+  return d;
+}
+
+function periodLabel(period) {
+  const months = ['Janeiro', 'Fevereiro', 'Março', 'Abril', 'Maio', 'Junho',
+    'Julho', 'Agosto', 'Setembro', 'Outubro', 'Novembro', 'Dezembro'];
+  if (period === 'week') return 'Últimos 7 dias';
+  if (period === 'all') return 'Histórico completo';
+  return `${months[new Date().getMonth()]} ${new Date().getFullYear()}`;
+}
+
+// ── Aggregator ─────────────────────────────────────────────────────────────────
+async function aggregateMetrics(metricsDir, period) {
   const dailyDir = path.join(metricsDir, 'daily');
+  const cutoff = cutoffDate(period);
+
   const stats = {
-    totalSessions: 0,
-    totalStories: 0,
-    totalTokens: 0,
-    agentUsage: {},
-    daysActive: 0
+    sessions: 0, stories: 0, tokens: 0,
+    agentUsage: {}, daysActive: 0,
+    memoryEntries: 0, commandsRun: 0,
+    firstDate: null, lastDate: null,
   };
 
-  if (!existsSync(dailyDir)) return stats;
+  if (!fsSync.existsSync(dailyDir)) return stats;
+
+  const files = (await fs.readdir(dailyDir))
+    .filter(f => f.match(/^\d{4}-\d{2}-\d{2}/) && (f.endsWith('.jsonl') || f.endsWith('.json')))
+    .filter(f => new Date(f.substring(0, 10)) >= cutoff)
+    .sort();
 
-  const files = (await fs.readdir(dailyDir)).filter(f => f.endsWith('.jsonl'));
   stats.daysActive = files.length;
+  if (files.length > 0) {
+    stats.firstDate = files[0].substring(0, 10);
+    stats.lastDate = files[files.length - 1].substring(0, 10);
+  }
 
   for (const file of files) {
     const content = await fs.readFile(path.join(dailyDir, file), 'utf8');
     const lines = content.split('\n').filter(l => l.trim());
-    
-    stats.totalSessions += lines.length;
+    stats.sessions += lines.length;
 
-    lines.forEach(line => {
+    for (const line of lines) {
       try {
         const entry = JSON.parse(line);
-        // Increment tokens if present
-        if (entry.tokens) stats.totalTokens += entry.tokens;
-        // Increment stories if entry marks completion
-        if (entry.type === 'story_complete') stats.totalStories += 1;
-        // Track agent usage
+        if (entry.tokens) stats.tokens += entry.tokens;
+        if (entry.type === 'story_complete') stats.stories += 1;
+        if (entry.type === 'memory_save') stats.memoryEntries += 1;
+        if (entry.type === 'command') stats.commandsRun += 1;
         if (entry.agent) {
           stats.agentUsage[entry.agent] = (stats.agentUsage[entry.agent] || 0) + 1;
         }
-      } catch (e) {
-        // Skip malformed lines
-      }
-    });
+      } catch (_) { /* skip bad lines */ }
+    }
   }
 
   return stats;
 }
 
-function showDashboard(stats) {
-  const monthNames = ["Janeiro", "Fevereiro", "Março", "Abril", "Maio", "Junho", "Julho", "Agosto", "Setembro", "Outubro", "Novembro", "Dezembro"];
-  const now = new Date();
-  
+// ── Manual event tracking ──────────────────────────────────────────────────────
+async function trackEvent(metricsDir, args) {
+  const type = args[0] || 'custom';
+  const content = args.slice(1).join(' ');
+  const today = new Date().toISOString().split('T')[0];
+  const dailyDir = path.join(metricsDir, 'daily');
+  if (!fsSync.existsSync(dailyDir)) await fs.mkdir(dailyDir, { recursive: true });
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    type,
+    content: content || type,
+  };
+  const file = path.join(dailyDir, `${today}.jsonl`);
+  await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf8');
+  console.log(`✅ Event tracked: [${type}] ${content || ''}`);
+}
+
+// ── Dashboard renderer ─────────────────────────────────────────────────────────
+function bar(value, max, width = 20) {
+  const filled = max > 0 ? Math.round((value / max) * width) : 0;
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function showDashboard(stats, period) {
+  const topAgents = Object.entries(stats.agentUsage).sort((a, b) => b[1] - a[1]).slice(0, 5);
+  const maxUsage = topAgents.length > 0 ? topAgents[0][1] : 0;
+
+  const sep = '─'.repeat(51);
+
   console.log(`
-📊 Grimoire Pro Metrics — ${monthNames[now.getMonth()]} ${now.getFullYear()}
-─────────────────────────────────────────────────
-  Sessões Totais:        ${stats.totalSessions}
-  Dias de Atividade:     ${stats.daysActive}
-  Stories Completas:     ${stats.totalStories}
-  Tokens Estimados:      ~${(stats.totalTokens / 1000).toFixed(1)}k
-─────────────────────────────────────────────────
-  Agentes mais ativos:`);
-
-  const topAgents = Object.entries(stats.agentUsage)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 3);
+📊 Grimoire Metrics — ${periodLabel(period)}
+${sep}
+  📅 Período           ${stats.firstDate || 'hoje'} → ${stats.lastDate || 'hoje'}
+  📆 Dias ativos       ${stats.daysActive}
+  🔄 Sessões totais    ${stats.sessions}
+  📖 Stories concluídas ${stats.stories}
+  💾 Entradas de memória ${stats.memoryEntries}
+  ⚡ Tokens estimados   ${stats.tokens > 0 ? '~' + (stats.tokens / 1000).toFixed(1) + 'k' : '(sem dados de hooks)'}
+${sep}
+  🤖 Agentes mais usados:`);
 
   if (topAgents.length > 0) {
     topAgents.forEach(([agent, count]) => {
-      console.log(`  - ${agent}: ${count} interações`);
+      const icon = AGENT_ICONS[agent] || '🎭';
+      const b = bar(count, maxUsage, 15);
+      console.log(`  ${icon} @${agent.padEnd(20)} ${b}  ${count}×`);
     });
   } else {
-    console.log('  (Nenhum dado de agente coletado ainda)');
+    console.log('  (Nenhum evento de agente registrado ainda)');
+    console.log('\n  💡 Para registrar uso: grimoire metrics track agent dev');
   }
 
-  console.log(`─────────────────────────────────────────────────
-💡 Dica: Os dados são coletados automaticamente via hooks.`);
+  console.log(`${sep}
+  💡 Dica: Use hooks para coletar dados automaticamente
+     grimoire metrics track story_complete "Login implementado"
+     grimoire metrics --period week
+     grimoire metrics export --csv
+`);
+}
+
+// ── CSV / Markdown export ──────────────────────────────────────────────────────
+async function exportMetrics(metricsDir, args) {
+  const format = args.includes('--csv') ? 'csv' : 'markdown';
+  const dailyDir = path.join(metricsDir, 'daily');
+
+  if (!fsSync.existsSync(dailyDir)) {
+    console.error('❌ No metrics data found.'); return;
+  }
+
+  const files = (await fs.readdir(dailyDir)).filter(f => f.match(/^\d{4}-\d{2}-\d{2}/)).sort();
+  const allEntries = [];
+
+  for (const file of files) {
+    const date = file.substring(0, 10);
+    const content = await fs.readFile(path.join(dailyDir, file), 'utf8');
+    const lines = content.split('\n').filter(l => l.trim());
+    for (const line of lines) {
+      try { allEntries.push({ date, ...JSON.parse(line) }); } catch (_) { }
+    }
+  }
+
+  const outPath = path.join(process.cwd(),
+    `grimoire-metrics-${new Date().toISOString().split('T')[0]}.${format === 'csv' ? 'csv' : 'md'}`);
+
+  if (format === 'csv') {
+    const headers = ['date', 'timestamp', 'type', 'agent', 'tokens', 'content'];
+    const rows = allEntries.map(e =>
+      headers.map(h => JSON.stringify(e[h] ?? '')).join(',')
+    );
+    await fs.writeFile(outPath, [headers.join(','), ...rows].join('\n'), 'utf8');
+  } else {
+    let md = '# Grimoire Metrics Export\n\n';
+    md += `> Exported: ${new Date().toISOString()}\n\n`;
+    md += `| Date | Time | Type | Agent | Tokens | Content |\n`;
+    md += `|------|------|------|-------|--------|---------|\n`;
+    allEntries.forEach(e => {
+      const time = e.timestamp ? e.timestamp.split('T')[1]?.split('.')[0] : '';
+      md += `| ${e.date} | ${time} | ${e.type || ''} | ${e.agent || ''} | ${e.tokens || ''} | ${e.content || ''} |\n`;
+    });
+    await fs.writeFile(outPath, md, 'utf8');
+  }
+
+  console.log(`✅ Metrics exported (${allEntries.length} events) → ${outPath}`);
+}
+
+// ── Help ───────────────────────────────────────────────────────────────────────
+function showHelp() {
+  console.log(`
+📊 Grimoire Metrics — Dashboard de Produtividade
+
+USO:
+  grimoire metrics                     Resumo do mês atual
+  grimoire metrics --period week       Últimos 7 dias
+  grimoire metrics --period month      Últimos 30 dias
+  grimoire metrics --period all        Histórico completo
+  grimoire metrics export --csv        Exportar para CSV
+  grimoire metrics export              Exportar para Markdown
+  grimoire metrics track <type> [msg]  Registrar evento manualmente
+
+TIPOS DE EVENTO:
+  story_complete  "Nome da story"   Marcar story como concluída
+  agent <name>                      Registrar uso de agente
+  command <cmd>                     Registrar comando executado
+  memory_save                       Registrar uso de memória
+  custom <desc>                     Evento personalizado
+
+EXEMPLOS:
+  grimoire metrics --period week
+  grimoire metrics track story_complete "Implementar login"
+  grimoire metrics track agent dev
+  grimoire metrics export --csv
+`);
 }
 
 module.exports = { run };

package/bin/commands/sync.js

@@ -0,0 +1,203 @@
+/**
+ * grimoire sync — Global Agent Synchronization
+ *
+ * Copies agents from the current project to a global ~/.grimoire/agents/
+ * and optionally syncs them to other projects on the machine.
+ *
+ * grimoire sync --global           Sync agents to global store
+ * grimoire sync --from-global      Pull global agents into current project
+ * grimoire sync --list             List global agents
+ * grimoire sync --projects         Show projects registered in global store
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const GLOBAL_DIR = path.join(os.homedir(), '.grimoire');
+const GLOBAL_AGENTS = path.join(GLOBAL_DIR, 'agents');
+const GLOBAL_REGISTRY = path.join(GLOBAL_DIR, 'projects.json');
+
+// ── Utilities ──────────────────────────────────────────────────────────────────
+function ensureGlobalDir() {
+    if (!fs.existsSync(GLOBAL_AGENTS)) fs.mkdirSync(GLOBAL_AGENTS, { recursive: true });
+}
+
+function loadRegistry() {
+    if (!fs.existsSync(GLOBAL_REGISTRY)) return { projects: [], lastSync: null };
+    try { return JSON.parse(fs.readFileSync(GLOBAL_REGISTRY, 'utf8')); }
+    catch (_) { return { projects: [], lastSync: null }; }
+}
+
+function saveRegistry(data) {
+    fs.writeFileSync(GLOBAL_REGISTRY, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function getLocalAgentsDir() {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, '.codex', 'agents');
+    if (!fs.existsSync(dir)) return null;
+    return dir;
+}
+
+function copyAgent(src, dest) {
+    const content = fs.readFileSync(src, 'utf8');
+    fs.writeFileSync(dest, content, 'utf8');
+}
+
+// ── Commands ───────────────────────────────────────────────────────────────────
+async function run(args) {
+    const sub = args.find(a => a.startsWith('--')) || '--global';
+
+    switch (sub) {
+        case '--global': await syncToGlobal(); break;
+        case '--from-global': await syncFromGlobal(); break;
+        case '--list': listGlobalAgents(); break;
+        case '--projects': listProjects(); break;
+        case '--help':
+        default: showHelp(); break;
+    }
+}
+
+// ── Sync local → global ────────────────────────────────────────────────────────
+async function syncToGlobal() {
+    const localDir = getLocalAgentsDir();
+    if (!localDir) {
+        console.error('❌ No .codex/agents/ found. Run: npx grimoire-framework install');
+        return;
+    }
+
+    ensureGlobalDir();
+
+    const agents = fs.readdirSync(localDir).filter(f => f.endsWith('.md'));
+    let synced = 0, skipped = 0;
+
+    console.log(`\n🌐 Syncing ${agents.length} agents to global store (~/.grimoire/agents/)...\n`);
+
+    for (const file of agents) {
+        const src = path.join(localDir, file);
+        const dest = path.join(GLOBAL_AGENTS, file);
+        const exists = fs.existsSync(dest);
+
+        // Compare content to decide if update is needed
+        if (exists) {
+            const srcContent = fs.readFileSync(src, 'utf8');
+            const destContent = fs.readFileSync(dest, 'utf8');
+            if (srcContent === destContent) { skipped++; continue; }
+        }
+
+        copyAgent(src, dest);
+        console.log(`  ✅ ${file.replace('.md', '')}`);
+        synced++;
+    }
+
+    if (skipped > 0) console.log(`  ⏩ ${skipped} already up-to-date (skipped)`);
+
+    // Register this project
+    const registry = loadRegistry();
+    const cwd = process.cwd();
+    if (!registry.projects.includes(cwd)) registry.projects.push(cwd);
+    registry.lastSync = new Date().toISOString();
+    saveRegistry(registry);
+
+    console.log(`\n✅ ${synced} agent${synced === 1 ? '' : 's'} synced to global store`);
+    console.log(`   ${GLOBAL_AGENTS}`);
+    console.log(`\n💡 Use "grimoire sync --from-global" in other projects to pull these agents`);
+}
+
+// ── Sync global → local ────────────────────────────────────────────────────────
+async function syncFromGlobal() {
+    if (!fs.existsSync(GLOBAL_AGENTS)) {
+        console.error('❌ No global agents found. Run "grimoire sync --global" first.');
+        return;
+    }
+
+    const localDir = getLocalAgentsDir();
+    if (!localDir) {
+        console.error('❌ No .codex/agents/ found. Run: npx grimoire-framework install');
+        return;
+    }
+
+    const globalAgents = fs.readdirSync(GLOBAL_AGENTS).filter(f => f.endsWith('.md'));
+    const localAgents = new Set(fs.readdirSync(localDir).filter(f => f.endsWith('.md')));
+
+    // Only pull agents that DON'T exist locally (preserve local customizations)
+    const newAgents = globalAgents.filter(f => !localAgents.has(f));
+
+    console.log(`\n📥 Pulling from global store (~/.grimoire/agents/)...\n`);
+    console.log(`  Global agents:  ${globalAgents.length}`);
+    console.log(`  Local agents:   ${localAgents.size}`);
+    console.log(`  New to pull:    ${newAgents.length}\n`);
+
+    if (newAgents.length === 0) {
+        console.log('✅ Local agents are already up-to-date with global store.');
+        return;
+    }
+
+    for (const file of newAgents) {
+        copyAgent(path.join(GLOBAL_AGENTS, file), path.join(localDir, file));
+        console.log(`  ✅ Added: @${file.replace('.md', '')}`);
+    }
+
+    console.log(`\n✅ ${newAgents.length} agent${newAgents.length === 1 ? '' : 's'} pulled from global store`);
+}
+
+// ── List global agents ─────────────────────────────────────────────────────────
+function listGlobalAgents() {
+    if (!fs.existsSync(GLOBAL_AGENTS)) {
+        console.log('ℹ️  No global agents yet. Run: grimoire sync --global');
+        return;
+    }
+
+    const agents = fs.readdirSync(GLOBAL_AGENTS).filter(f => f.endsWith('.md'));
+    const registry = loadRegistry();
+
+    console.log(`\n🌐 Global Grimoire Agents (${agents.length})`);
+    console.log(`   Store: ${GLOBAL_AGENTS}`);
+    if (registry.lastSync) console.log(`   Last sync: ${registry.lastSync.split('T')[0]}\n`);
+
+    agents.forEach(f => console.log(`  🤖 @${f.replace('.md', '')}`));
+}
+
+// ── List registered projects ───────────────────────────────────────────────────
+function listProjects() {
+    const registry = loadRegistry();
+    console.log(`\n📁 Projects using Grimoire global store (${registry.projects.length}):\n`);
+    if (registry.projects.length === 0) {
+        console.log('  (No projects registered yet — run "grimoire sync --global")');
+        return;
+    }
+    registry.projects.forEach(p => {
+        const exists = fs.existsSync(p);
+        console.log(`  ${exists ? '✅' : '❌'} ${p}`);
+    });
+}
+
+// ── Help ───────────────────────────────────────────────────────────────────────
+function showHelp() {
+    console.log(`
+🌐 Grimoire Sync — Sincronização Global de Agentes
+
+USO:
+  grimoire sync --global           Envia agentes locais para ~/.grimoire/agents/
+  grimoire sync --from-global      Puxa agentes globais para o projeto atual
+  grimoire sync --list             Lista agentes no store global
+  grimoire sync --projects         Lista projetos registrados
+
+FLUXO TÍPICO:
+  # No projeto A (onde você criou um agente customizado):
+  grimoire agent create  →  grimoire sync --global
+
+  # No projeto B (onde você quer esse agente):
+  grimoire sync --from-global
+
+NOTAS:
+  - --from-global nunca sobrescreve agentes existentes localmente
+  - --global sobrescreve apenas se o conteúdo mudou
+  - O store global fica em: ${GLOBAL_DIR}
+`);
+}
+
+module.exports = { run };

package/bin/commands/update.js

@@ -24,6 +24,7 @@ const FRAMEWORK_SYNC_DIRS = [
     { src: '.gemini/rules/grimoire', dest: '.gemini/rules/grimoire' },
     { src: '.cursor/rules/agents', dest: '.cursor/rules/agents' },
     { src: '.claude/commands/grimoire', dest: '.claude/commands/grimoire' },
+    { src: 'squads', dest: '.grimoire/squads' },
 ];
 
 // Single files to sync (framework root → project root)

package/bin/grimoire-cli.js

@@ -12,8 +12,93 @@ const { execSync } = require('child_process');
 const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 const args = process.argv.slice(2);
 const command = args[0];
+const currentVersion = packageJson.version;
+
+// ── Update Banner (async, non-blocking, 24h cooldown) ─────────────────────────
+const UPDATE_CACHE_FILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || require('os').homedir(),
+  '.grimoire-update-cache.json'
+);
+
+function shouldCheckForUpdates() {
+  if (process.env.GRIMOIRE_NO_UPDATE_CHECK) return false;
+  if (['update', '--version', '-v', 'doctor'].includes(command)) return false;
+  try {
+    if (fs.existsSync(UPDATE_CACHE_FILE)) {
+      const cache = JSON.parse(fs.readFileSync(UPDATE_CACHE_FILE, 'utf8'));
+      const hoursSince = (Date.now() - cache.lastCheck) / (1000 * 60 * 60);
+      if (hoursSince < 24) return false;
+    }
+  } catch (e) { /* ignore */ }
+  return true;
+}
+
+async function checkForUpdates() {
+  if (!shouldCheckForUpdates()) return;
+  try {
+    const https = require('https');
+    const data = await new Promise((resolve, reject) => {
+      const req = https.get(
+        'https://registry.npmjs.org/grimoire-framework/latest',
+        { timeout: 3000 },
+        (res) => {
+          let body = '';
+          res.on('data', d => body += d);
+          res.on('end', () => { try { resolve(JSON.parse(body)); } catch (e) { reject(e); } });
+        }
+      );
+      req.on('error', reject);
+      req.on('timeout', () => req.destroy());
+    });
+    const latest = data.version;
+    // Save to cache
+    fs.writeFileSync(UPDATE_CACHE_FILE, JSON.stringify({ lastCheck: Date.now(), latest }));
+    // Compare versions
+    const [maj, min, pat] = currentVersion.split('.').map(Number);
+    const [lmaj, lmin, lpat] = latest.split('.').map(Number);
+    const isNewer = lmaj > maj || (lmaj === maj && lmin > min) || (lmaj === maj && lmin === min && lpat > pat);
+    if (isNewer) {
+      console.log(`\n💡 Nova versão disponível: v${latest} (você tem v${currentVersion})`);
+      console.log(`   Atualize com: npx grimoire-framework update\n`);
+    }
+  } catch (e) { /* offline ou erro — ignorar silenciosamente */ }
+}
+
+// ── First-Run Experience ───────────────────────────────────────────────────────
+function showNextSteps(projectDir) {
+  const cwd = projectDir || process.cwd();
+  // Detect installed IDE
+  const hasGemini = fs.existsSync(path.join(cwd, 'GEMINI.md'));
+  const hasCursor = fs.existsSync(path.join(cwd, '.cursor'));
+  const hasClaude = fs.existsSync(path.join(cwd, '.claude'));
+
+  let ideStep = '   2. Abra o Gemini CLI:  gemini';
+  if (hasClaude) ideStep = '   2. Abra o Claude Code — agentes prontos com /dev, /qa, /architect';
+  else if (hasCursor) ideStep = '   2. Abra o Cursor — @dev, @qa, @architect disponíveis no chat';
+  else if (hasGemini) ideStep = '   2. Abra o Gemini CLI:  gemini  →  Michelangelo te recebe';
+
+  const agentsDir = path.join(cwd, '.codex', 'agents');
+  const agentCount = fs.existsSync(agentsDir)
+    ? fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length : 0;
+
+  console.log(`
+🎯 Próximos passos:
+   1. Verifique a instalação:  grimoire status
+${ideStep}
+   3. Para ver todos os agentes: grimoire agents list
+   4. Para diagnóstico:           grimoire doctor
+
+💡 Dica rápida: Diga \"@dev implementa o login\" no chat da sua IDE
+   Você tem ${agentCount} agentes prontos: @dev, @qa, @architect, @grimoire-master...
+
+📚 Docs: https://github.com/gabrielrlima/grimoire#readme
+`);
+}
 
 async function main() {
+  // Non-blocking update check (runs in background)
+  const updatePromise = checkForUpdates().catch(() => { });
+
   switch (command) {
     case 'memory':
       await require('./commands/memory').run(args.slice(1));
@@ -27,6 +112,12 @@ async function main() {
     case 'agents':
       handleAgents(args.slice(1));
       break;
+    case 'agent':
+      await require('./commands/agent').run(args.slice(1));
+      break;
+    case 'sync':
+      await require('./commands/sync').run(args.slice(1));
+      break;
     case 'status':
       handleStatus();
       break;
@@ -47,7 +138,7 @@ async function main() {
       break;
     case '--version':
     case '-v':
-      console.log(`Grimoire Pro v${packageJson.version}`);
+      console.log(`Grimoire v${packageJson.version}`);
       break;
     case '--help':
     case '-h':
@@ -55,6 +146,9 @@ async function main() {
       showHelp();
       break;
   }
+
+  // Wait for update check to finish (prints banner after main command if needed)
+  await updatePromise;
 }
 
 function handleSquads(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grimoire-framework",
-  "version": "1.0.18",
+  "version": "1.0.21",
   "description": "Grimoire: AI-Orchestrated System for Full Stack Development - Core Framework",
   "publishConfig": {
     "access": "public"
@@ -36,6 +36,7 @@
     ".claude/hooks/",
     "GEMINI.md",
     "pro/license/",
+    "squads/",
     "README.md",
     "LICENSE"
   ],