@eximia-ventures/claude-code-toolkit 3.1.1 → 3.2.1

package/README.md

@@ -194,6 +194,42 @@ npx @eximia-ventures/claude-code-toolkit doctor
   ✓ Tudo OK! (10 verificações passaram)
 ```
 
+### `update [module]`
+
+Atualiza os módulos já instalados sem passar pelo wizard. Lê o manifest, re-executa a instalação de cada módulo e usa hash comparison para pular arquivos que já estão em dia.
+
+```bash
+# Atualizar tudo
+npx @eximia-ventures/claude-code-toolkit update
+
+# Atualizar apenas um módulo
+npx @eximia-ventures/claude-code-toolkit update aios
+npx @eximia-ventures/claude-code-toolkit update statusline
+npx @eximia-ventures/claude-code-toolkit update handoff
+npx @eximia-ventures/claude-code-toolkit update meter
+```
+
+```
+  ─── Atualização ───
+
+  ℹ Instalação encontrada (v3.2.0, 3 módulos)
+
+  ─── Statusline ───
+
+  ✓ Statusline já atualizada em ~/.claude/statusline.sh
+  ✓ settings.json atualizado com statusLine
+
+  ─── Session Handoff ───
+
+  ✓ claude-code-handoff instalado (7 commands, 2 hooks, 2 rules)
+
+  ─── AIOS Framework ───
+
+  ✓ Skill /aios-integrate já atualizada
+
+  ✓ Atualização completa (3 atualizado(s), 0 já em dia)
+```
+
 ### `uninstall`
 
 Remove tudo que foi instalado, baseado no manifest:
@@ -296,6 +332,7 @@ claude-code-toolkit/
 │   │   └── aios.js                   # npx aios-core + skill
 │   ├── commands/
 │   │   ├── uninstall.js              # Remoção via manifest
+│   │   ├── update.js                 # Atualização sem wizard
 │   │   └── doctor.js                 # 10 checks de integridade
 │   └── utils/
 │       ├── settings-merger.js        # Deep-merge seguro (com backup)

package/assets/skill/aios-integrate.md

@@ -83,6 +83,90 @@ Ao finalizar, mostre um relatório:
   Manifest atualizado: agents.csv
 ```
 
+#### Auto-Explain: Guia de Uso
+
+Imediatamente após exibir o relatório de integração, gere automaticamente um **Guia de Uso** educativo do artefato integrado. O guia é obrigatório — não pergunte ao usuário se deseja; sempre gere.
+
+**Regras gerais:**
+1. Sempre em português
+2. Tom educativo e acessível — como se estivesse ensinando alguém a usar pela primeira vez
+3. Máximo ~40 linhas
+4. Use APENAS dados reais extraídos do artefato — nunca invente comandos, campos ou comportamentos
+5. Omita seções para as quais não há dados disponíveis no artefato
+6. Use tabelas markdown para comandos e agents
+
+**Para Agent** — gere as seguintes seções (quando os dados existirem):
+
+| Seção | O que mostrar | Fonte dos dados |
+|-------|---------------|-----------------|
+| **O que é** | Descrição do papel do agent em 1-2 frases | `persona.role` + `agent.whenToUse` |
+| **Como ativar** | Sintaxe de ativação (`@{id}`) e tom de interação | `agent.id`, `persona_profile.archetype`, `communication.tone` |
+| **Comandos disponíveis** | Tabela com nome, descrição e exemplo de uso | `commands[]` filtrados por `visibility` = `quick` ou `key` |
+| **Quando usar** | Situações práticas em que o agent é útil | `agent.whenToUse` ou inferido de `persona.role` |
+| **Exemplo prático** | Um cenário realista de uso com saudação e primeiro comando | `greeting_levels.named` + primeiro comando disponível |
+| **Dependências** | Contagem por categoria (tasks, templates, checklists) | `dependencies` (se existir) |
+
+Formato de saída para Agent:
+```markdown
+## 📖 Guia de Uso: {agent-name}
+
+### O que é
+{descrição baseada em persona.role e whenToUse}
+
+### Como ativar
+Chame `@{id}` para ativar. {tom de interação baseado em archetype/tone}
+
+### Comandos disponíveis
+| Comando | Descrição |
+|---------|-----------|
+| `*{cmd}` | {descrição} |
+
+### Quando usar
+{situações práticas}
+
+### Exemplo prático
+> Usuário: @{id} olá
+> Agent: {saudação named}
+> Usuário: *{primeiro-comando}
+
+### Dependências
+{N} tasks, {N} templates, {N} checklists
+```
+
+**Para Squad** — gere as seguintes seções (quando os dados existirem):
+
+| Seção | O que mostrar | Fonte dos dados |
+|-------|---------------|-----------------|
+| **O que é** | Descrição do squad em 1-2 frases | `description` do squad |
+| **Agents incluídos** | Tabela com agent, papel e como ativar | `components.agents[]` |
+| **Comandos disponíveis** | Tabela com comandos usando o prefixo do squad | `components.tasks[]` com `slashPrefix` |
+| **Workflow típico** | Sequência de uso recomendada | Inferido de `components.workflows[]` ou composição dos agents |
+| **Componentes** | Resumo quantitativo | Contagem de agents, tasks, workflows, templates |
+
+Formato de saída para Squad:
+```markdown
+## 📖 Guia de Uso: {squad-name}
+
+### O que é
+{descrição do squad}
+
+### Agents incluídos
+| Agent | Papel | Ativação |
+|-------|-------|----------|
+| {name} | {role} | `@{id}` |
+
+### Comandos disponíveis
+| Comando | Descrição |
+|---------|-----------|
+| `/{prefix}-{task}` | {descrição} |
+
+### Workflow típico
+{sequência de uso recomendada}
+
+### Componentes
+{N} agents, {N} tasks, {N} workflows, {N} templates
+```
+
 ---
 
 ### 3. Listar Artefatos Instalados

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eximia-ventures/claude-code-toolkit",
-  "version": "3.1.1",
+  "version": "3.2.1",
   "description": "Setup completo para Claude Code: statusline, session handoff, AIOS integration",
   "main": "src/index.js",
   "bin": {

package/src/commands/update.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const logger = require('../utils/logger');
+const { MANIFEST_PATH } = require('../installer');
+const modules = require('../modules');
+
+const VALID_MODULES = Object.keys(modules);
+
+async function runUpdate(moduleName) {
+  logger.section('Atualização');
+
+  // Check manifest
+  if (!(await fs.pathExists(MANIFEST_PATH))) {
+    logger.warn('Nenhuma instalação encontrada (manifest ausente).');
+    logger.dim('Execute primeiro: npx @eximia-ventures/claude-code-toolkit');
+    return;
+  }
+
+  const manifest = await fs.readJson(MANIFEST_PATH);
+  const installed = manifest.modules || [];
+
+  logger.info(`Instalação encontrada (v${manifest.version}, ${installed.length} módulos)`);
+  logger.dim(`Módulos: ${installed.join(', ')}`);
+
+  // Determine which modules to update
+  let toUpdate;
+  if (moduleName) {
+    if (!VALID_MODULES.includes(moduleName)) {
+      logger.error(`Módulo desconhecido: ${moduleName}`);
+      logger.dim(`Disponíveis: ${VALID_MODULES.join(', ')}`);
+      return;
+    }
+    if (!installed.includes(moduleName)) {
+      logger.warn(`Módulo "${moduleName}" não está instalado.`);
+      logger.dim(`Instalados: ${installed.join(', ')}`);
+      return;
+    }
+    toUpdate = [moduleName];
+  } else {
+    toUpdate = installed;
+  }
+
+  if (toUpdate.length === 0) {
+    logger.warn('Nenhum módulo para atualizar.');
+    return;
+  }
+
+  let updated = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  // Update each module
+  for (const mod of toUpdate) {
+    try {
+      const result = await updateModule(mod, manifest);
+      if (result === 'updated') updated++;
+      else skipped++;
+    } catch (err) {
+      logger.error(`Falha ao atualizar ${modules[mod].name}: ${err.message}`);
+      failed++;
+    }
+  }
+
+  // Update manifest metadata
+  manifest.version = require('../../package.json').version;
+  manifest.updatedAt = new Date().toISOString();
+  await fs.writeJson(MANIFEST_PATH, manifest, { spaces: 2 });
+
+  // Summary
+  logger.blank();
+  if (failed === 0) {
+    logger.success(`Atualização completa (${updated} atualizado(s), ${skipped} já em dia)`);
+  } else {
+    logger.warn(`${updated} atualizado(s), ${skipped} em dia, ${failed} com falha`);
+  }
+}
+
+async function updateModule(name, manifest) {
+  switch (name) {
+    case 'statusline': {
+      logger.section('Statusline');
+      const result = await modules.statusline.module.install({});
+      return result.installed ? 'updated' : 'skipped';
+    }
+
+    case 'handoff': {
+      const result = await modules.handoff.module.install();
+      return result.installed ? 'updated' : 'skipped';
+    }
+
+    case 'meter': {
+      const result = await modules.meter.module.install();
+      return result.installed ? 'updated' : 'skipped';
+    }
+
+    case 'aios': {
+      const opts = {
+        installAiosCore: manifest.aiosCore || false,
+        installAiosSkill: true
+      };
+      const result = await modules.aios.module.install(opts);
+      return 'updated';
+    }
+
+    default:
+      logger.dim(`Módulo sem rotina de update: ${name}`);
+      return 'skipped';
+  }
+}
+
+module.exports = { runUpdate };

package/src/index.js

@@ -6,6 +6,7 @@ const logger = require('./utils/logger');
 const { runInstaller } = require('./installer');
 const { runUninstall } = require('./commands/uninstall');
 const { runDoctor } = require('./commands/doctor');
+const { runUpdate } = require('./commands/update');
 
 const program = new Command();
 
@@ -46,6 +47,19 @@ program
     }
   });
 
+program
+  .command('update [module]')
+  .description('Atualiza módulos instalados (todos ou um específico)')
+  .action(async (moduleName) => {
+    logger.banner(pkg.version);
+    try {
+      await runUpdate(moduleName);
+    } catch (err) {
+      logger.error(`Erro: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .description('Verifica integridade da instalação')