grimoire-framework 1.1.1 → 1.3.0

package/.grimoire/install-manifest.yaml

@@ -7,8 +7,8 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.1.1
-generated_at: "2026-02-22T15:03:35.007Z"
+version: 1.3.0
+generated_at: "2026-02-22T16:50:35.905Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1011
 files:

package/bin/commands/agent.js

@@ -100,6 +100,7 @@ async function run(args) {
     switch (sub) {
         case 'create': await createWizard(); break;
         case 'edit': await editAgent(args[1]); break;
+        case 'validate': validateAgent(args[1]); break;
         case 'remove':
         case 'delete': await removeAgent(args[1]); break;
         case 'list':
@@ -191,6 +192,43 @@ Para sincronizar com outras IDEs:
 `);
 }
 
+function validateAgent(id) {
+    if (!id) { console.log('Usage: grimoire agent validate <name>'); return; }
+    const file = path.join(process.cwd(), '.codex', 'agents', `${id}.md`);
+    if (!fs.existsSync(file)) { console.log(`❌ Agent "${id}" not found in .codex/agents/`); return; }
+
+    const content = fs.readFileSync(file, 'utf8');
+    const checks = [
+        { name: 'YAML block (`\`\`\`yaml`)', pass: content.includes('```yaml') },
+        { name: 'activation-instructions', pass: content.includes('activation-instructions') },
+        { name: 'STEP 1 / STEP 2 / STEP 3', pass: /STEP 1/.test(content) && /STEP 2/.test(content) },
+        { name: 'agent.name defined', pass: /\bname:\s*\S+/.test(content) },
+        { name: 'agent.id defined', pass: /\bid:\s*\S+/.test(content) },
+        { name: 'agent.icon defined', pass: /\bicon:\s*\S+/.test(content) },
+        { name: 'greeting_levels present', pass: content.includes('greeting_levels') },
+        { name: 'signature_closing present', pass: content.includes('signature_closing') },
+        { name: 'ACTIVATION-NOTICE present', pass: content.includes('ACTIVATION-NOTICE') },
+        { name: '*exit command referenced', pass: content.includes('*exit') },
+    ];
+
+    const passed = checks.filter(c => c.pass).length;
+    const score = Math.round((passed / checks.length) * 100);
+    const emoji = score === 100 ? '🟢' : score >= 70 ? '🟡' : '🔴';
+
+    console.log(`\n🔍 Agent Validation: @${id}\n${'─'.repeat(40)}`);
+    checks.forEach(c => console.log(`  ${c.pass ? '✅' : '❌'} ${c.name}`));
+    console.log(`${'─'.repeat(40)}`);
+    console.log(`  ${emoji} Score: ${score}/100 (${passed}/${checks.length} checks)\n`);
+
+    if (score < 100) {
+        console.log('  Fixes sugeridos:');
+        checks.filter(c => !c.pass).forEach(c => console.log(`    → Adicionar: ${c.name}`));
+        console.log();
+    } else {
+        console.log('  ✅ Agente válido e pronto para uso!\n');
+    }
+}
+
 async function editAgent(id) {
     if (!id) { console.log('Usage: grimoire agent edit <name>'); return; }
     const file = path.join(process.cwd(), '.codex', 'agents', `${id}.md`);

package/bin/commands/config.js

@@ -0,0 +1,181 @@
+/**
+ * grimoire config — Project-level configuration
+ *
+ * grimoire config get <key>         Lê valor de uma chave
+ * grimoire config set <key> <value> Define valor de uma chave
+ * grimoire config list              Lista todas as configurações
+ * grimoire config reset             Reseta para os defaults
+ *
+ * Config file: .grimoire/config.yaml
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// ── Defaults ───────────────────────────────────────────────────────────────────
+const DEFAULTS = {
+    default_agent: 'grimoire-master',
+    memory_auto_save: false,
+    update_check_interval: 24,          // hours
+    metrics_enabled: true,
+    hooks_enabled: false,
+    marketplace_cache_ttl: 60,          // minutes
+    language: 'pt-BR',
+};
+
+const DESCRIPTIONS = {
+    default_agent: 'Agente padrão ao iniciar o IDE',
+    memory_auto_save: 'Salvar memória automaticamente ao encerrar sessão',
+    update_check_interval: 'Intervalo de horas entre verificações de atualização',
+    metrics_enabled: 'Habilitar coleta de métricas de produtividade',
+    hooks_enabled: 'Habilitar git hooks para auto-tracking de commits',
+    marketplace_cache_ttl: 'Tempo de cache do marketplace em minutos',
+    language: 'Idioma preferido para prompts e saídas',
+};
+
+// ── File location ──────────────────────────────────────────────────────────────
+function findConfigFile() {
+    const cwd = process.cwd();
+    const direct = path.join(cwd, '.grimoire', 'config.yaml');
+    const subdir = path.join(cwd, 'grimoire', '.grimoire', 'config.yaml');
+    if (fs.existsSync(direct)) return direct;
+    if (fs.existsSync(subdir)) return subdir;
+    // Return direct path for writing even if it doesn't exist
+    const grimoireDir = path.join(cwd, '.grimoire');
+    if (fs.existsSync(grimoireDir)) return direct;
+    return null;
+}
+
+// ── Minimal YAML parser/writer ─────────────────────────────────────────────────
+function parseYaml(content) {
+    const result = {};
+    for (const line of content.split('\n')) {
+        const stripped = line.trim();
+        if (!stripped || stripped.startsWith('#')) continue;
+        const colonIdx = stripped.indexOf(':');
+        if (colonIdx === -1) continue;
+        const key = stripped.slice(0, colonIdx).trim();
+        let val = stripped.slice(colonIdx + 1).trim();
+        // Parse types
+        if (val === 'true') val = true;
+        else if (val === 'false') val = false;
+        else if (!isNaN(val) && val !== '') val = Number(val);
+        result[key] = val;
+    }
+    return result;
+}
+
+function toYaml(obj) {
+    const lines = ['# Grimoire Framework — Project Configuration', '# grimoire config set <key> <value> to edit', ''];
+    for (const [k, v] of Object.entries(obj)) {
+        const desc = DESCRIPTIONS[k];
+        if (desc) lines.push(`# ${desc}`);
+        lines.push(`${k}: ${v}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+
+function loadConfig() {
+    const file = findConfigFile();
+    if (!file || !fs.existsSync(file)) return { ...DEFAULTS };
+    try {
+        return { ...DEFAULTS, ...parseYaml(fs.readFileSync(file, 'utf8')) };
+    } catch (_) { return { ...DEFAULTS }; }
+}
+
+function saveConfig(obj) {
+    const cwd = process.cwd();
+    let grimoireDir = path.join(cwd, '.grimoire');
+    if (!fs.existsSync(grimoireDir)) {
+        const sub = path.join(cwd, 'grimoire', '.grimoire');
+        if (fs.existsSync(sub)) grimoireDir = sub;
+        else { console.error('❌ .grimoire/ not found. Run: npx grimoire-framework install'); return false; }
+    }
+    const file = path.join(grimoireDir, 'config.yaml');
+    fs.writeFileSync(file, toYaml(obj), 'utf8');
+    return true;
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+function getConfigValue(key) {
+    return loadConfig()[key];
+}
+
+// ── Commands ───────────────────────────────────────────────────────────────────
+function run(args) {
+    const sub = args[0];
+    const key = args[1];
+    const value = args[2];
+
+    switch (sub) {
+        case 'set': configSet(key, value); break;
+        case 'reset': configReset(); break;
+        case 'get':
+            if (!key) { configList(); break; }
+            configGet(key); break;
+        case 'list':
+        default: configList(); break;
+    }
+}
+
+function configGet(key) {
+    if (!key) { configList(); return; }
+    const config = loadConfig();
+    if (!(key in config)) {
+        console.log(`❌ Chave desconhecida: "${key}"`);
+        console.log(`   Chaves válidas: ${Object.keys(DEFAULTS).join(', ')}\n`);
+        return;
+    }
+    console.log(`${key} = ${config[key]}`);
+}
+
+function configSet(key, value) {
+    if (!key || value === undefined) {
+        console.log('Usage: grimoire config set <key> <value>');
+        console.log('Ex:    grimoire config set default_agent dev\n');
+        return;
+    }
+    if (!(key in DEFAULTS)) {
+        console.log(`❌ Chave desconhecida: "${key}"`);
+        console.log(`   Chaves válidas: ${Object.keys(DEFAULTS).join(', ')}\n`);
+        return;
+    }
+    const config = loadConfig();
+    // Type coerce
+    let coerced = value;
+    if (value === 'true') coerced = true;
+    else if (value === 'false') coerced = false;
+    else if (!isNaN(value)) coerced = Number(value);
+
+    config[key] = coerced;
+    if (saveConfig(config)) {
+        console.log(`✅ ${key} = ${coerced}`);
+    }
+}
+
+function configList() {
+    const config = loadConfig();
+    const file = findConfigFile();
+    console.log(`\n⚙️  Grimoire Config${file && fs.existsSync(file) ? ` (${path.relative(process.cwd(), file)})` : ' (defaults)'}\n`);
+    console.log('  ' + '─'.repeat(48));
+    for (const [k, v] of Object.entries(DEFAULTS)) {
+        const current = config[k];
+        const isDef = current === v;
+        const marker = isDef ? '  ' : '✏️ ';
+        console.log(`  ${marker} ${k.padEnd(28)} ${String(current)}`);
+    }
+    console.log('  ' + '─'.repeat(48));
+    console.log(`  💡 grimoire config set <key> <value>  para alterar`);
+    console.log(`  💡 grimoire config reset              para restaurar defaults\n`);
+}
+
+function configReset() {
+    if (saveConfig({ ...DEFAULTS })) {
+        console.log('✅ Configuração restaurada para os defaults.\n');
+    }
+}
+
+module.exports = { run, getConfigValue, loadConfig };

package/bin/commands/hooks.js

@@ -0,0 +1,137 @@
+/**
+ * grimoire hooks — Git Hook Integration for Auto-Metrics Tracking
+ *
+ * grimoire hooks install      Instala post-commit hook no repositório atual
+ * grimoire hooks uninstall    Remove o hook
+ * grimoire hooks status       Verifica se o hook está instalado
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const HOOK_MARKER = '# grimoire-hook-v1';
+const HOOK_CONTENT = `#!/bin/sh
+${HOOK_MARKER}
+# Auto-installed by Grimoire Framework
+# Remove with: grimoire hooks uninstall
+
+# Get commit message (first line)
+COMMIT_MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1)
+
+# Track the commit in grimoire metrics (non-blocking)
+grimoire metrics track commit "$COMMIT_MSG" 2>/dev/null &
+
+exit 0
+`;
+
+function findGitDir() {
+    let dir = process.cwd();
+    for (let i = 0; i < 8; i++) {
+        if (fs.existsSync(path.join(dir, '.git'))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return null;
+}
+
+function run(args) {
+    const sub = args[0] || 'status';
+    switch (sub) {
+        case 'install': install(); break;
+        case 'uninstall': uninstall(); break;
+        case 'status':
+        default: status(); break;
+    }
+}
+
+function install() {
+    const gitRoot = findGitDir();
+    if (!gitRoot) {
+        console.error('❌ Repositório git não encontrado. Execute dentro de um projeto git.');
+        return;
+    }
+
+    const hooksDir = path.join(gitRoot, '.git', 'hooks');
+    const hookFile = path.join(hooksDir, 'post-commit');
+
+    if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+
+    // Check if hook already exists and isn't ours
+    if (fs.existsSync(hookFile)) {
+        const existing = fs.readFileSync(hookFile, 'utf8');
+        if (existing.includes(HOOK_MARKER)) {
+            console.log('ℹ️  Hook já instalado. Use "grimoire hooks status" para verificar.');
+            return;
+        }
+        // Append to existing hook
+        const updated = existing.trimEnd() + '\n\n' + HOOK_CONTENT;
+        fs.writeFileSync(hookFile, updated, 'utf8');
+    } else {
+        fs.writeFileSync(hookFile, HOOK_CONTENT, 'utf8');
+    }
+
+    // Make executable (Unix/Mac — no-op on Windows but harmless)
+    try { fs.chmodSync(hookFile, '755'); } catch (_) { }
+
+    console.log(`
+✅ grimoire hooks instalado!
+
+   Hook: .git/hooks/post-commit
+   Efeito: commits são automaticamente registrados em grimoire metrics
+
+   Próximo passo: faça um git commit e execute:
+   grimoire metrics --period week
+
+   Para remover: grimoire hooks uninstall
+`);
+}
+
+function uninstall() {
+    const gitRoot = findGitDir();
+    if (!gitRoot) { console.error('❌ Repositório git não encontrado.'); return; }
+
+    const hookFile = path.join(gitRoot, '.git', 'hooks', 'post-commit');
+    if (!fs.existsSync(hookFile)) {
+        console.log('ℹ️  Nenhum hook encontrado.');
+        return;
+    }
+
+    const content = fs.readFileSync(hookFile, 'utf8');
+    if (!content.includes(HOOK_MARKER)) {
+        console.log('ℹ️  Hook não foi instalado pelo Grimoire. Nada removido.');
+        return;
+    }
+
+    // If our hook is the only content, delete the file
+    const lines = content.split('\n');
+    const otherLines = lines.filter(l => !l.includes(HOOK_MARKER) && !l.includes('grimoire metrics track'));
+    const cleaned = otherLines.join('\n').trim();
+
+    if (!cleaned || cleaned === '#!/bin/sh') {
+        fs.unlinkSync(hookFile);
+        console.log('✅ Hook removido (arquivo deletado).');
+    } else {
+        fs.writeFileSync(hookFile, cleaned + '\n', 'utf8');
+        console.log('✅ Hook grimoire removido (conteúdo do hook preservado).');
+    }
+}
+
+function status() {
+    const gitRoot = findGitDir();
+    if (!gitRoot) { console.log('⚠️  Repositório git não encontrado.\n'); return; }
+
+    const hookFile = path.join(gitRoot, '.git', 'hooks', 'post-commit');
+    const exists = fs.existsSync(hookFile);
+    const isOurs = exists && fs.readFileSync(hookFile, 'utf8').includes(HOOK_MARKER);
+
+    console.log('\n🪝 Grimoire Hooks\n' + '─'.repeat(40));
+    console.log(`  post-commit: ${isOurs ? '✅ instalado' : exists ? '⚠️  arquivo existe (não é nosso)' : '⭕ não instalado'}`);
+    if (!isOurs) console.log(`\n  Para instalar: grimoire hooks install`);
+    else console.log(`\n  Para remover:  grimoire hooks uninstall`);
+    console.log();
+}
+
+module.exports = { run };

package/bin/commands/memory.js

@@ -35,6 +35,9 @@ async function run(args) {
       case 'save':
         await saveMemory(args.slice(1), memoryDir);
         break;
+      case 'list-tags':
+        await listTags(memoryDir);
+        break;
       case 'list':
         await listSessions(memoryDir);
         break;
@@ -67,7 +70,22 @@ async function run(args) {
  * Saves memory using JSONL append (O(1) complexity)
  */
 async function saveMemory(args, memoryDir) {
-  const content = args.join(' ');
+  // Extract --tag value if present
+  const tagIdx = args.findIndex(a => a === '--tag' || a.startsWith('--tag='));
+  let tag = null;
+  let filteredArgs = [...args];
+  if (tagIdx !== -1) {
+    if (args[tagIdx].includes('=')) {
+      tag = args[tagIdx].split('=')[1];
+    } else {
+      tag = args[tagIdx + 1];
+      filteredArgs.splice(tagIdx, 2);
+    }
+    if (!tag) { filteredArgs.splice(tagIdx, 1); }
+    else { filteredArgs = filteredArgs.filter(a => a !== args[tagIdx] && a !== tag); }
+  }
+
+  const content = filteredArgs.join(' ');
   if (!content) {
     console.error('❌ Please provide content to save.');
     return;
@@ -78,7 +96,8 @@ async function saveMemory(args, memoryDir) {
 
   const entry = {
     timestamp: new Date().toISOString(),
-    content: content
+    content: content,
+    ...(tag ? { tag } : {}),
   };
 
   // Ensure file exists for lockfile
@@ -100,7 +119,8 @@ async function saveMemory(args, memoryDir) {
 
     // Append entry as a new line in JSONL format
     await fs.appendFile(sessionFile, JSON.stringify(entry) + '\n', 'utf8');
-    console.log(`✅ Memory appended to session ${today} (JSONL)`);
+    const tagLabel = tag ? ` [#${tag}]` : '';
+    console.log(`✅ Memory appended to session ${today}${tagLabel}`);
   } catch (err) {
     console.error(`❌ Failed to acquire lock for memory file: ${err.message}`);
   } finally {
@@ -120,6 +140,37 @@ async function listSessions(memoryDir) {
   files.forEach(f => console.log(`  - ${f.replace('.jsonl', '').replace('.json', '')}`));
 }
 
+/**
+ * Lists all unique tags across all sessions
+ */
+async function listTags(memoryDir) {
+  const sessionsDir = path.join(memoryDir, 'sessions');
+  let files;
+  try { files = (await fs.readdir(sessionsDir)).filter(f => f.endsWith('.jsonl')); }
+  catch (_) { files = []; }
+
+  const tagCount = {};
+  for (const file of files) {
+    const raw = await fs.readFile(path.join(sessionsDir, file), 'utf8').catch(() => '');
+    for (const line of raw.split('\n').filter(l => l.trim())) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.tag) tagCount[entry.tag] = (tagCount[entry.tag] || 0) + 1;
+      } catch (_) { }
+    }
+  }
+
+  const tags = Object.entries(tagCount).sort((a, b) => b[1] - a[1]);
+  console.log('\n🏷️  Grimoire Memory Tags:\n');
+  if (tags.length === 0) {
+    console.log('  (nenhuma tag registrada)');
+    console.log('  Use: grimoire memory save --tag <nome> "texto"\n');
+    return;
+  }
+  tags.forEach(([tag, count]) => console.log(`  #${tag.padEnd(20)} ${count}×`));
+  console.log(`\n  Para filtrar: grimoire memory search --tag <nome>\n`);
+}
+
 /**
  * Shows session parsing JSONL or legacy JSON
  */

package/bin/commands/report.js

@@ -0,0 +1,200 @@
+/**
+ * grimoire report — Daily / Weekly Consolidated Report
+ *
+ * grimoire report               Relatório de hoje
+ * grimoire report --period week Última semana (7 dias)
+ * grimoire report --period all  Histórico completo
+ * grimoire report --md          Exporta para .grimoire/reports/YYYY-MM-DD.md
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+function findGrimoireDir() {
+    const cwd = process.cwd();
+    const direct = path.join(cwd, '.grimoire');
+    const sub = path.join(cwd, 'grimoire', '.grimoire');
+    if (fs.existsSync(direct)) return direct;
+    if (fs.existsSync(sub)) return sub;
+    return null;
+}
+
+// ── Date helpers ───────────────────────────────────────────────────────────────
+function today() { return new Date().toISOString().split('T')[0]; }
+function daysAgo(n) {
+    const d = new Date();
+    d.setDate(d.getDate() - n);
+    return d.toISOString().split('T')[0];
+}
+function dateRange(period) {
+    if (period === 'week') return { from: daysAgo(6), to: today(), label: 'semana' };
+    if (period === 'month') return { from: daysAgo(29), to: today(), label: 'mês' };
+    return { from: '2000-01-01', to: today(), label: 'histórico' };
+}
+
+// ── Helpers: read JSONL sessions ───────────────────────────────────────────────
+function readSessionEntries(grimoireDir, from, to) {
+    const sessionsDir = path.join(grimoireDir, 'memory', 'sessions');
+    if (!fs.existsSync(sessionsDir)) return [];
+    const files = fs.readdirSync(sessionsDir)
+        .filter(f => f.endsWith('.jsonl') && f.slice(0, 10) >= from && f.slice(0, 10) <= to);
+    const entries = [];
+    for (const f of files) {
+        const raw = fs.readFileSync(path.join(sessionsDir, f), 'utf8');
+        for (const line of raw.split('\n').filter(l => l.trim())) {
+            try { entries.push({ date: f.slice(0, 10), ...JSON.parse(line) }); } catch (_) { }
+        }
+    }
+    return entries;
+}
+
+// ── Helpers: read metrics JSONL ────────────────────────────────────────────────
+function readMetricsEntries(grimoireDir, from, to) {
+    const metricsDir = path.join(grimoireDir, 'metrics');
+    if (!fs.existsSync(metricsDir)) return [];
+    const files = fs.readdirSync(metricsDir)
+        .filter(f => f.endsWith('.jsonl') && f.slice(0, 10) >= from && f.slice(0, 10) <= to);
+    const entries = [];
+    for (const f of files) {
+        const raw = fs.readFileSync(path.join(metricsDir, f), 'utf8');
+        for (const line of raw.split('\n').filter(l => l.trim())) {
+            try { entries.push({ date: f.slice(0, 10), ...JSON.parse(line) }); } catch (_) { }
+        }
+    }
+    return entries;
+}
+
+// ── Read stories ───────────────────────────────────────────────────────────────
+function readStories(grimoireDir, from, to) {
+    const storiesDir = path.join(grimoireDir, 'stories');
+    if (!fs.existsSync(storiesDir)) return [];
+    return fs.readdirSync(storiesDir)
+        .filter(f => f.endsWith('.json'))
+        .map(f => { try { return JSON.parse(fs.readFileSync(path.join(storiesDir, f), 'utf8')); } catch (_) { return null; } })
+        .filter(Boolean)
+        .filter(s => s.createdAt && s.createdAt.slice(0, 10) >= from);
+}
+
+// ── Build report object ────────────────────────────────────────────────────────
+function buildReport(grimoireDir, period) {
+    const { from, to, label } = dateRange(period);
+    const memEntries = readSessionEntries(grimoireDir, from, to);
+    const metricEntries = readMetricsEntries(grimoireDir, from, to);
+    const stories = readStories(grimoireDir, from, to);
+
+    // Tag buckets
+    const byTag = {};
+    for (const e of memEntries) {
+        if (e.tag) {
+            byTag[e.tag] = byTag[e.tag] || [];
+            byTag[e.tag].push(e);
+        }
+    }
+
+    // Agent usage from metrics
+    const agentUse = {};
+    for (const e of metricEntries) {
+        if (e.agent) agentUse[e.agent] = (agentUse[e.agent] || 0) + 1;
+        if (e.type === 'agent_session' && e.agent) agentUse[e.agent] = (agentUse[e.agent] || 0) + 1;
+    }
+    const topAgents = Object.entries(agentUse).sort((a, b) => b[1] - a[1]).slice(0, 5);
+
+    // Metrics summary
+    const sessions = metricEntries.filter(e => e.type === 'session_start' || e.type === 'session' || e.type === 'agent_session').length;
+    const commits = metricEntries.filter(e => e.type === 'commit').length;
+    const done = stories.filter(s => s.status === 'done').length;
+    const open = stories.filter(s => s.status !== 'done').length;
+
+    return { from, to, label, memEntries, byTag, topAgents, sessions, commits, stories, done, open };
+}
+
+// ── Render text report ─────────────────────────────────────────────────────────
+function renderReport(r) {
+    const lines = [];
+    const sep = '═'.repeat(50);
+    lines.push(`\n📊 Grimoire Report — ${r.to}  (${r.label}: ${r.from} → ${r.to})`);
+    lines.push(sep);
+
+    // Metrics
+    lines.push('\n📈 Métricas:');
+    lines.push(`  Sessões:  ${r.sessions}   Commits: ${r.commits}   Stories: ${r.done} concluídas / ${r.open} abertas`);
+    if (r.topAgents.length) {
+        lines.push(`  Agentes: ${r.topAgents.map(([a, n]) => `@${a} (${n}×)`).join(' · ')}`);
+    }
+
+    // Memory by tag
+    const tagKeys = Object.keys(r.byTag);
+    if (tagKeys.length > 0) {
+        lines.push('\n🧠 Memória por tag:');
+        for (const tag of tagKeys) {
+            lines.push(`\n  #${tag}:`);
+            for (const e of r.byTag[tag].slice(0, 5)) {
+                lines.push(`    ${e.date}  ${e.content}`);
+            }
+        }
+    }
+
+    // Untagged entries summary
+    const untagged = r.memEntries.filter(e => !e.tag);
+    if (untagged.length) {
+        lines.push(`\n🗒️  Memórias sem tag: ${untagged.length} entradas`);
+        untagged.slice(0, 3).forEach(e => lines.push(`  ${e.date}  ${e.content}`));
+        if (untagged.length > 3) lines.push(`  ... e mais ${untagged.length - 3}`);
+    }
+
+    // Stories
+    if (r.stories.length > 0) {
+        lines.push('\n📋 Stories:');
+        r.stories.filter(s => s.status === 'done').forEach(s =>
+            lines.push(`  ✅ [${s.id}] ${s.title} — concluída`)
+        );
+        r.stories.filter(s => s.status !== 'done').forEach(s =>
+            lines.push(`  🔄 [${s.id}] ${s.title} — em andamento`)
+        );
+    }
+
+    if (r.memEntries.length === 0 && r.sessions === 0 && r.stories.length === 0) {
+        lines.push('\n  (nenhuma atividade registrada no período)');
+        lines.push('  Dica: grimoire memory save "texto" · grimoire metrics track session');
+    }
+
+    lines.push('\n' + sep + '\n');
+    return lines.join('\n');
+}
+
+// ── Main run ───────────────────────────────────────────────────────────────────
+function run(args) {
+    const grimoireDir = findGrimoireDir();
+    if (!grimoireDir) {
+        console.error('❌ .grimoire/ not found. Run: npx grimoire-framework install');
+        return;
+    }
+
+    const periodIdx = args.findIndex(a => a === '--period' || a.startsWith('--period='));
+    let period = 'day';
+    if (periodIdx !== -1) {
+        period = args[periodIdx].includes('=')
+            ? args[periodIdx].split('=')[1]
+            : (args[periodIdx + 1] || 'day');
+    } else if (args.includes('week')) {
+        period = 'week';
+    }
+
+    const exportMd = args.includes('--md');
+    const report = buildReport(grimoireDir, period);
+    const text = renderReport(report);
+
+    console.log(text);
+
+    if (exportMd) {
+        const reportsDir = path.join(grimoireDir, 'reports');
+        if (!fs.existsSync(reportsDir)) fs.mkdirSync(reportsDir, { recursive: true });
+        const filename = path.join(reportsDir, `${report.to}-${period}.md`);
+        fs.writeFileSync(filename, text.replace(/\n/g, '\n'), 'utf8');
+        console.log(`✅ Relatório exportado: ${path.relative(process.cwd(), filename)}\n`);
+    }
+}
+
+module.exports = { run };