@omnizap-system/omnizap 2.6.0 → 2.6.2

package/app/modules/aiModule/commandConfig.json

@@ -146,7 +146,7 @@
       "aliases": ["cat"],
       "descricao": "Perguntas para IA com suporte opcional a resposta em audio.",
       "metodos_de_uso": ["<prefix>ia sua pergunta", "<prefix>ia --audio sua pergunta"],
-      "permissao_necessaria": "usuario comum",
+      "permissao_necessaria": "usuario premium",
       "limite_de_uso": "texto sujeito a limites da API",
       "local_de_uso": ["privado", "grupo"],
       "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "prompt textual enviado ao modelo de IA", "flags de resposta (ex.: audio/voz)", "midia anexada/citada para analise multimodal (quando houver)", "identidade do usuario para sessao e contexto de conversa"],
@@ -205,8 +205,8 @@
       "user_phrasings": ["quero usar ia", "me ajuda com ia", "perguntas para ia com"],
       "suggestion_priority": 100,
       "acesso": {
-        "somente_premium": false,
-        "planos_permitidos": ["comum", "premium"]
+        "somente_premium": true,
+        "planos_permitidos": ["premium"]
       },
       "limite_uso_por_plano": {
         "comum": {
@@ -224,14 +224,16 @@
         "default": ["*<prefix>ia* [--audio] sua pergunta", "*<prefix>ia* (responda ou envie uma imagem com legenda)", "", "Opções:", "--audio | --texto", "--detail low | high | auto", "", "Exemplo:", "*<prefix>ia* Explique como funciona a fotossíntese.", "*<prefix>ia* --audio Resuma a imagem."]
       },
       "mensagens_sistema": {
-        "premium_only": "⭐ *Comando Premium*\n\nEste comando é exclusivo para usuários premium.\nFale com o administrador para liberar o acesso.",
-        "openai_nao_configurada": "⚠️ *OpenAI não configurada*\n\nDefina a variável *OPENAI_API_KEY* no `.env` para usar o comando *cat*.",
-        "imagem_muito_grande": "⚠️ A imagem enviada ultrapassa o limite de {{limite_mb}} MB. Envie uma imagem menor.",
-        "imagem_download_falhou": "⚠️ Não consegui baixar a imagem. Tente reenviar.",
-        "resposta_vazia": "⚠️ Não consegui gerar uma resposta agora. Tente novamente.",
-        "audio_muito_longo": "⚠️ A resposta ficou longa demais para áudio. Enviando em texto.",
-        "audio_falhou": "⚠️ Não consegui gerar o áudio agora. Enviando texto.",
-        "erro_openai": "❌ *Erro ao falar com a IA*\nTente novamente em alguns instantes."
+        "premium_only": "⭐ *Recurso Premium*\n\nEste comando é exclusivo para usuários Premium.\nPara liberar o acesso, fale com o admin do sistema no privado.",
+        "openai_nao_configurada": "⚠️ *IA indisponível no momento*\n\nEste recurso está em manutenção.\nSe precisar de ajuda, fale com o admin do sistema no privado.",
+        "imagem_muito_grande": "⚠️ A imagem está muito grande para análise (limite {{limite_mb}} MB). Envie uma imagem menor.",
+        "imagem_download_falhou": "⚠️ Não consegui ler sua imagem agora. Reenvie a imagem.\nSe o erro continuar, fale com o admin do sistema no privado.",
+        "resposta_vazia": "⚠️ Não consegui montar uma resposta agora. Tente novamente em instantes.",
+        "audio_muito_longo": "⚠️ A resposta ficou grande para áudio. Vou te enviar em texto.",
+        "audio_falhou": "⚠️ Não consegui gerar o áudio agora. Vou te responder em texto.",
+        "erro_openai": "❌ *Não consegui responder agora*\n\nTente novamente em instantes.\nSe o erro continuar, fale com o admin do sistema no privado.",
+        "usage_header": "🤖 *Comando CAT*",
+        "resposta_prefixo_texto": "🐈‍⬛ "
       },
       "opcoes": {
         "parse": {
@@ -260,7 +262,7 @@
           "default": ["*<prefix>ia* [--audio] sua pergunta", "*<prefix>ia* (responda ou envie uma imagem com legenda)", "", "Opções:", "--audio | --texto", "--detail low | high | auto", "", "Exemplo:", "*<prefix>ia* Explique como funciona a fotossíntese.", "*<prefix>ia* --audio Resuma a imagem."]
         }
       },
-      "permission": "usuario comum",
+      "permission": "usuario premium",
       "contexts": ["privado", "grupo"],
       "collected_data": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "prompt textual enviado ao modelo de IA", "flags de resposta (ex.: audio/voz)", "midia anexada/citada para analise multimodal (quando houver)", "identidade do usuario para sessao e contexto de conversa"],
       "requirements": {
@@ -321,8 +323,8 @@
           "escopo": "sem_rate_limit_explicito"
         },
         "access": {
-          "somente_premium": false,
-          "planos_permitidos": ["comum", "premium"]
+          "somente_premium": true,
+          "planos_permitidos": ["premium"]
         },
         "plan_limits": {
           "comum": {
@@ -371,11 +373,11 @@
         "suggestion_priority": 100
       },
       "access": {
-        "premium_only": false,
-        "allowed_plans": ["comum", "premium"],
+        "premium_only": true,
+        "allowed_plans": ["premium"],
         "legacy": {
-          "somente_premium": false,
-          "planos_permitidos": ["comum", "premium"]
+          "somente_premium": true,
+          "planos_permitidos": ["premium"]
         }
       },
       "plan_limits": {
@@ -404,6 +406,23 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "ia",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Permite fazer perguntas à IA diretamente pelo chat, com opção de ouvir a resposta em áudio. Ideal para respostas rápidas, explicações simples ou conteúdos curtos.",
+        "quando_usar": ["Quando quiser uma resposta direta da IA para uma pergunta simples.", "Quando desejar a resposta em áudio (opção disponível).", "Quando houver contexto com mídia para a IA considerar na resposta."],
+        "exemplos_reais": [
+          {
+            "situacao": "Pergunta rápida sobre fato.",
+            "comando": "<prefix>ia qual é a capital da França",
+            "resposta_esperada": "Paris.",
+            "variacao": "variante com áudio: <prefix>ia --audio qual é a capital da França; variante com alias: <prefix>cat qual é a capital da França."
+          }
+        ],
+        "resposta_esperada": ["Resposta direta da IA conforme a pergunta; se áudio foi solicitado, exibe também o áudio correspondente."],
+        "erros_comuns_usuario": ["Esquecer de usar o prefixo correto (<prefix>).", "Usar o formato de uso errado ou ignorar os métodos de uso.", "Tentar usar o recurso de áudio sem ter acesso necessário (premium).", "Fazer perguntas vagas ou sem contexto suficiente.", "Não especificar claramente o que precisa na pergunta."],
+        "passos_se_der_erro": ["Verifique se o comando está no formato certo: <prefix>ia sua pergunta.", "Se pedir áudio, confirme que o seu plano permite áudio (premium).", "Corrija o texto da pergunta e tente novamente: <prefix>ia sua pergunta", "Caso o erro persista, tente a versão com alias: <prefix>cat sua pergunta", "Se precisar, procure ajuda para confirmar detalhes da sua assinatura ou suporte do serviço"],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     },
     {
@@ -411,7 +430,7 @@
       "aliases": ["catimage", "catimg"],
       "descricao": "Gera/edita imagem com IA por prompt.",
       "metodos_de_uso": ["<prefix>iaimagem seu prompt", "<prefix>iaimagem --size 1536x1024 seu prompt"],
-      "permissao_necessaria": "usuario comum",
+      "permissao_necessaria": "usuario premium",
       "limite_de_uso": "imagem de entrada ate OPENAI_MAX_IMAGE_MB (padrao 50 MB)",
       "local_de_uso": ["privado", "grupo"],
       "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "prompt de geracao/edicao de imagem", "opcoes de geracao (size, quality, format, background)", "imagem enviada/citada para edicao (quando houver)"],
@@ -503,13 +522,16 @@
         "default": ["*<prefix>iaimagem* seu prompt", "*<prefix>iaimagem* (responda uma imagem com legenda para editar)", "", "Opções:", "--size 1024x1024 | 1024x1536 | 1536x1024 | auto", "--quality low | medium | high | auto", "--format png | jpeg | webp", "--background transparent | opaque | auto", "--compression 0-100", "", "Exemplo:", "*<prefix>iaimagem* --size 1536x1024 Um gato astronauta em aquarela."]
       },
       "mensagens_sistema": {
-        "premium_only": "⭐ *Comando Premium*\n\nEste comando é exclusivo para usuários premium.\nFale com o administrador para liberar o acesso.",
-        "openai_nao_configurada": "⚠️ *OpenAI não configurada*\n\nDefina a variável *OPENAI_API_KEY* no `.env` para usar o comando *catimg*.",
-        "imagem_muito_grande": "⚠️ A imagem enviada ultrapassa o limite de {{limite_mb}} MB. Envie uma imagem menor.",
-        "imagem_download_falhou": "⚠️ Não consegui baixar a imagem. Tente reenviar.",
-        "opcoes_invalidas": "⚠️ Opções inválidas no comando.\nDetalhes: {{detalhes}}\n\nUse *{{prefix}}catimg* sem opções para ver o formato correto.",
-        "resposta_vazia": "⚠️ Não consegui gerar a imagem agora. Tente novamente.",
-        "erro_openai": "❌ *Erro ao falar com a IA*\nTente novamente em alguns instantes."
+        "premium_only": "⭐ *Recurso Premium*\n\nEste comando é exclusivo para usuários Premium.\nPara liberar o acesso, fale com o admin do sistema no privado.",
+        "openai_nao_configurada": "⚠️ *Gerador de imagem indisponível*\n\nEste recurso está em manutenção.\nSe precisar de ajuda, fale com o admin do sistema no privado.",
+        "imagem_muito_grande": "⚠️ A imagem está muito grande para edição (limite {{limite_mb}} MB). Envie uma imagem menor.",
+        "imagem_download_falhou": "⚠️ Não consegui ler sua imagem agora. Reenvie a imagem.\nSe o erro continuar, fale com o admin do sistema no privado.",
+        "opcoes_invalidas": "⚠️ Algumas opções do comando estão inválidas.\nDetalhes: {{detalhes}}\n\nUse *{{prefix}}catimg* sem opções para ver o formato correto.",
+        "resposta_vazia": "⚠️ Não consegui gerar a imagem agora. Tente novamente em instantes.",
+        "erro_openai": "❌ *Não consegui gerar sua imagem agora*\n\nTente novamente em instantes.\nSe o erro continuar, fale com o admin do sistema no privado.",
+        "usage_header": "🖼️ *Imagem IA*",
+        "resposta_prefixo_texto_imagem": "🖼️ ",
+        "imagem_caption_sucesso": "🖼️ Imagem gerada."
       },
       "opcoes": {
         "geracao_imagem": {
@@ -575,7 +597,7 @@
           "default": ["*<prefix>iaimagem* seu prompt", "*<prefix>iaimagem* (responda uma imagem com legenda para editar)", "", "Opções:", "--size 1024x1024 | 1024x1536 | 1536x1024 | auto", "--quality low | medium | high | auto", "--format png | jpeg | webp", "--background transparent | opaque | auto", "--compression 0-100", "", "Exemplo:", "*<prefix>iaimagem* --size 1536x1024 Um gato astronauta em aquarela."]
         }
       },
-      "permission": "usuario comum",
+      "permission": "usuario premium",
       "contexts": ["privado", "grupo"],
       "collected_data": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "prompt de geracao/edicao de imagem", "opcoes de geracao (size, quality, format, background)", "imagem enviada/citada para edicao (quando houver)"],
       "requirements": {
@@ -745,6 +767,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "iaimagem",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Gerar ou editar imagens com IA a partir de um prompt via <prefix>iaimagem. Você pode ajustar o tamanho com --size, escolher qualidade e formato. Algumas funções são Premium.",
+        "quando_usar": ["Quero criar uma imagem a partir de uma descrição simples.", "Quero definir o tamanho da imagem (por exemplo, 1024x1024 ou 1536x1024).", "Quero escolher qualidade ou formato de saída (png, jpeg, webp).", "Preciso de recursos avançados que exigem assinatura Premium."],
+        "exemplos_reais": [
+          {
+            "situacao": "Gerar imagem simples a partir do prompt.",
+            "comando": "<prefix>iaimagem pôr do sol sobre o mar",
+            "resposta_esperada": "Imagem gerada com sucesso.",
+            "variacao": "sem --size para usar o tamanho padrão."
+          },
+          {
+            "situacao": "Gerar imagem com tamanho específico.",
+            "comando": "<prefix>iaimagem --size 1536x1024 cidade futurista ao entardecer",
+            "resposta_esperada": "Imagem gerada com sucesso.",
+            "variacao": "inclui --size 1536x1024."
+          },
+          {
+            "situacao": "Gerar imagem com qualidade alta (Premium).",
+            "comando": "<prefix>iaimagem --size 1024x1024 --quality high retrato iluminado",
+            "resposta_esperada": "Imagem gerada com sucesso.",
+            "variacao": "requer assinatura Premium."
+          }
+        ],
+        "resposta_esperada": ["Imagem gerada com sucesso.", "Formato de uso inválido. Consulte metodos_de_uso.", "Permissão insuficiente para executar este comando."],
+        "erros_comuns_usuario": ["Esquecer de fornecer um prompt descritivo", "Usar tamanho ou formato não suportado", "Não ter acesso Premium quando o recurso exigir assinatura", "Não estar logado (Google Login necessário quando requerido)"],
+        "passos_se_der_erro": ["Copie o comando com o <prefix> correto e tente novamente", "Inclua um prompt claro que descreva a imagem desejada", "Se usar --size, escolha entre 1024x1024, 1024x1536 ou 1536x1024", "Defina --format (png|jpeg|webp) e --quality (auto|low|medium|high) se necessário", "Verifique se você tem a assinatura Premium para recursos avançados"],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     },
     {
@@ -826,7 +877,8 @@
         "premium_only": "⭐ *Comando Premium*\n\nEste comando é exclusivo para usuários premium.\nFale com o administrador para liberar o acesso.",
         "prompt_muito_longo": "⚠️ Prompt muito longo. Limite: {{max_chars}} caracteres.",
         "prompt_reset_sucesso": "✅ Prompt da IA restaurado para o padrão.",
-        "prompt_update_sucesso": "✅ Prompt da IA atualizado para você."
+        "prompt_update_sucesso": "✅ Prompt da IA atualizado para você.",
+        "usage_header": "🧠 *Prompt da IA*"
       },
       "limites_operacionais": {
         "prompt_max_chars": 2000
@@ -972,6 +1024,40 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "pergunteia",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "opcoes": {
+        "parse": {
+          "reset_aliases": ["reset", "default", "padrao", "padrão"]
+        }
+      },
+      "user_experience": {
+        "resumo_usuario": "Defina ou redefina o seu prompt personalizado da IA. Envie o conteúdo desejado ou use reset para voltar ao padrão. Após o envio, a IA responderá conforme o prompt configurado.",
+        "quando_usar": ["Quero orientar a IA para um estilo específico de respostas (tom, foco, formato).", "Preciso que as respostas sigam um conjunto de instruções definidas (ex.: curto, passo a passo, com exemplos).", "Quero limpar o prompt atual e voltar ao comportamento padrão da IA."],
+        "exemplos_reais": [
+          {
+            "situacao": "Definir respostas objetivas para estudo em ciências.",
+            "comando": "<prefix>pergunteia novo prompt Responda resumidamente com 3 fatos-chave sobre cada tema.",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "Tom direto, menos detalhes, foco no essencial."
+          },
+          {
+            "situacao": "Resetar o prompt para o comportamento padrão.",
+            "comando": "<prefix>pergunteia reset",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "Limpeza completa do prompt atual."
+          },
+          {
+            "situacao": "Configurar tom formal para atendimento.",
+            "comando": "<prefix>pergunteia novo prompt Responda de forma formal, com passos práticos e exemplos quando apropriado.",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "Tom profissional, orientado a ações."
+          }
+        ],
+        "resposta_esperada": ["Ao executar um comando válido, a IA atualiza o prompt conforme informado e responde de acordo com o novo prompt. Em caso de sucesso, costuma aparecer: 'Comando executado com sucesso.'"],
+        "erros_comuns_usuario": ["Esquecer de incluir o texto do prompt após o comando <prefix>pergunteia novo prompt.", "Não fechar aspas ou usar formatação inadequada no conteúdo do prompt.", "Não usar o prefix correto ou digitar o comando em lugar errado.", "Tentar usar o reset sem entender o impacto (volta ao comportamento padrão).", "Definir um prompt vago ou ambíguo que não orienta a IA de forma clara."],
+        "passos_se_der_erro": ["Verifique se o comando segue o formato: '<prefix>pergunteia novo prompt <texto>' ou '<prefix>pergunteia reset'.", "Confirme que você está logado com Google Login, conforme exigido.", "Tente novamente com um prompt simples para confirmar funcionamento.", "Se retornar 'Formato de uso inválido', ajuste o comando para o formato correto e tente novamente.", "Se aparecer 'Permissão insuficiente', confirme se você tem acesso necessário ou peça ao admin para liberar."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],

package/app/modules/analyticsModule/messageAnalysisEventRepository.js

@@ -36,7 +36,11 @@ const sanitizeMetadata = (value) => {
   }
 };
 
+let messageAnalysisSessionColumnSupported = true;
+
 export async function createMessageAnalysisEvent(payload = {}, connection = null) {
+  const sessionId = sanitizeText(payload.sessionId || payload.session_id, 64) || 'default';
+  const ownerSessionId = sanitizeText(payload.ownerSessionId || payload.owner_session_id || payload?.metadata?.owner_session_id, 64);
   const messageId = sanitizeText(payload.messageId, 255);
   const chatId = sanitizeText(payload.chatId, 255);
   const senderId = sanitizeText(payload.senderId, 255);
@@ -49,9 +53,42 @@ export async function createMessageAnalysisEvent(payload = {}, connection = null
   const processingResult = sanitizeText(payload.processingResult, 64) || 'processed';
   const errorCode = sanitizeText(payload.errorCode, 96);
   const metadata = sanitizeMetadata(payload.metadata);
+  const isGroup = sanitizeBool(payload.isGroup);
+
+  if (isGroup && ownerSessionId && ownerSessionId !== sessionId) {
+    return false;
+  }
+
+  const valuesWithSession = [sessionId, messageId, chatId, senderId, senderName, upsertType, source, isGroup, sanitizeBool(payload.isFromBot), sanitizeBool(payload.isCommand), commandName, clampInt(payload.commandArgsCount, 0, 0, 64), payload.commandKnown === null || payload.commandKnown === undefined ? null : sanitizeBool(payload.commandKnown), commandPrefix, messageKind, sanitizeBool(payload.hasMedia), clampInt(payload.mediaCount, 0, 0, 25), clampInt(payload.textLength, 0, 0, 16_000), processingResult, errorCode, metadata];
+  const valuesWithoutSession = valuesWithSession.slice(1);
+
+  const sqlWithSession = `INSERT INTO ${TABLES.MESSAGE_ANALYSIS_EVENT}
+      (
+        session_id,
+        message_id,
+        chat_id,
+        sender_id,
+        sender_name,
+        upsert_type,
+        source,
+        is_group,
+        is_from_bot,
+        is_command,
+        command_name,
+        command_args_count,
+        command_known,
+        command_prefix,
+        message_kind,
+        has_media,
+        media_count,
+        text_length,
+        processing_result,
+        error_code,
+        metadata
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
 
-  await executeQuery(
-    `INSERT INTO ${TABLES.MESSAGE_ANALYSIS_EVENT}
+  const sqlWithoutSession = `INSERT INTO ${TABLES.MESSAGE_ANALYSIS_EVENT}
       (
         message_id,
         chat_id,
@@ -74,10 +111,21 @@ export async function createMessageAnalysisEvent(payload = {}, connection = null
         error_code,
         metadata
       )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    [messageId, chatId, senderId, senderName, upsertType, source, sanitizeBool(payload.isGroup), sanitizeBool(payload.isFromBot), sanitizeBool(payload.isCommand), commandName, clampInt(payload.commandArgsCount, 0, 0, 64), payload.commandKnown === null || payload.commandKnown === undefined ? null : sanitizeBool(payload.commandKnown), commandPrefix, messageKind, sanitizeBool(payload.hasMedia), clampInt(payload.mediaCount, 0, 0, 25), clampInt(payload.textLength, 0, 0, 16_000), processingResult, errorCode, metadata],
-    connection,
-  );
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+
+  if (messageAnalysisSessionColumnSupported) {
+    try {
+      await executeQuery(sqlWithSession, valuesWithSession, connection);
+      return true;
+    } catch (error) {
+      if (error?.code !== 'ER_BAD_FIELD_ERROR') {
+        throw error;
+      }
+      messageAnalysisSessionColumnSupported = false;
+    }
+  }
+
+  await executeQuery(sqlWithoutSession, valuesWithoutSession, connection);
 
   return true;
 }

package/app/modules/gameModule/AGENT.md

@@ -7,7 +7,7 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - arquivo_base: `app/modules/gameModule/commandConfig.json`
 - schema_version: `2.0.0`
 - module_enabled: `true`
-- generated_at: `2026-03-11T02:35:17.177Z`
+- generated_at: `2026-03-17T04:04:14.195Z`
 
 ## Escopo do Modulo
 

package/app/modules/gameModule/commandConfig.json

@@ -357,6 +357,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "dado",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Rola um dado com número de lados opcional. Se não informar, usa 6. Use <prefix>dado, <prefix>dado <lados> ou <prefix>dice <lados> para obter um resultado entre 1 e o número de lados (até 1000).",
+        "quando_usar": ["Precisa de um número aleatório para jogos de tabuleiro, RPG ou simulações.", "Quero um dado específico de lados para um desafio ou teste.", "Vou jogar com dados com mais de 6 lados (até 1000)."],
+        "exemplos_reais": [
+          {
+            "situacao": "Rolar dado padrão (6 lados).",
+            "comando": "<prefix>dado",
+            "resposta_esperada": "Você rolou um dado de 6 lados: 4.",
+            "variacao": "Pode também usar <prefix>dado para o mesmo resultado."
+          },
+          {
+            "situacao": "Rolar dado de 20 lados.",
+            "comando": "<prefix)dado 20",
+            "resposta_esperada": "Você rolou um dado de 20 lados: 13.",
+            "variacao": "ou <prefix>dice 20."
+          },
+          {
+            "situacao": "Rolar dado de 100 lados.",
+            "comando": "<prefix>dice 100",
+            "resposta_esperada": "Você rolou um dado de 100 lados: 87.",
+            "variacao": "ou <prefix>dado 100."
+          }
+        ],
+        "resposta_esperada": ["Resultado do dado: <valor>", "Você rolou um dado de <lados> lados: <valor>"],
+        "erros_comuns_usuario": ["Formato de uso inválido. Use um dos formatos: <prefix>dado, <prefix>dado <lados> ou <prefix>dice <lados>.", "O número de lados precisa estar entre 2 e 1000.", "Informar um valor não numérico ou caracteres.", "Esquecer de incluir o <prefix> ao digitar o comando."],
+        "passos_se_der_erro": ["Leia a mensagem de erro com atenção e ajuste o comando para um formato válido.", "Verifique se o valor de lados está entre 2 e 1000 quando informado.", "Use exatamente um dos formatos: <prefix>dado, <prefix>dado <lados> ou <prefix>dice <lados>.", "Se o problema persistir, confirme que você está logado com Google e tente novamente.", "Se ainda assim não funcionar, peça ajuda ao suporte."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],

package/app/modules/menuModule/AGENT.md

@@ -7,7 +7,7 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - arquivo_base: `app/modules/menuModule/commandConfig.json`
 - schema_version: `2.0.0`
 - module_enabled: `true`
-- generated_at: `2026-03-11T02:35:17.177Z`
+- generated_at: `2026-03-17T04:04:14.195Z`
 
 ## Escopo do Modulo
 

package/app/modules/menuModule/commandConfig.json

@@ -144,15 +144,15 @@
     {
       "name": "menu",
       "aliases": [],
-      "descricao": "Exibe o menu principal ou um menu por categoria.",
-      "metodos_de_uso": ["<prefix>menu", "<prefix>menu anime", "<prefix>menu stats"],
+      "descricao": "Exibe o menu dinâmico de comandos (com destaques por uso), categorias e atalhos para catálogo completo.",
+      "metodos_de_uso": ["<prefix>menu", "<prefix>menu top", "<prefix>menu categoria <nome>", "<prefix>menu todos", "<prefix>menu anime", "<prefix>menu stats"],
       "permissao_necessaria": "usuario comum",
       "limite_de_uso": "sem limite especifico",
       "local_de_uso": ["privado", "grupo"],
       "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "categoria solicitada no menu (quando informada)"],
       "enabled": true,
       "categoria": "menu",
-      "subcomandos": ["figurinhas", "sticker", "stickers", "midia", "media", "quote", "quotes", "ia", "ai", "stats", "estatisticas", "anime"],
+      "subcomandos": ["top", "todos", "categoria", "figurinhas", "sticker", "stickers", "midia", "media", "quote", "quotes", "ia", "ai", "stats", "estatisticas", "anime"],
       "argumentos": [
         {
           "nome": "categoria",
@@ -214,16 +214,22 @@
         }
       },
       "mensagens_uso": {
-        "default": ["<prefix>menu", "<prefix>menu anime", "<prefix>menu stats"]
+        "default": ["<prefix>menu", "<prefix>menu top", "<prefix>menu categoria <nome>", "<prefix>menu todos", "<prefix>menu anime", "<prefix>menu stats"],
+        "category": ["<prefix>menu categoria <nome>"],
+        "top": ["<prefix>menu top"],
+        "all": ["<prefix>menu todos"]
       },
       "id": "menu.menu",
-      "description": "Exibe o menu principal ou um menu por categoria.",
-      "usage": ["<prefix>menu", "<prefix>menu anime", "<prefix>menu stats"],
+      "description": "Exibe o menu dinâmico de comandos (com destaques por uso), categorias e atalhos para catálogo completo.",
+      "usage": ["<prefix>menu", "<prefix>menu top", "<prefix>menu categoria <nome>", "<prefix>menu todos", "<prefix>menu anime", "<prefix>menu stats"],
       "docs": {
-        "summary": "Exibe o menu principal ou um menu por categoria.",
-        "usage_examples": ["<prefix>menu", "<prefix>menu anime", "<prefix>menu stats"],
+        "summary": "Exibe o menu dinâmico de comandos (com destaques por uso), categorias e atalhos para catálogo completo.",
+        "usage_examples": ["<prefix>menu", "<prefix>menu top", "<prefix>menu categoria <nome>", "<prefix>menu todos", "<prefix>menu anime", "<prefix>menu stats"],
         "usage_variants": {
-          "default": ["<prefix>menu", "<prefix>menu anime", "<prefix>menu stats"]
+          "default": ["<prefix>menu", "<prefix>menu top", "<prefix>menu categoria <nome>", "<prefix>menu todos", "<prefix>menu anime", "<prefix>menu stats"],
+          "category": ["<prefix>menu categoria <nome>"],
+          "top": ["<prefix>menu top"],
+          "all": ["<prefix>menu todos"]
         }
       },
       "permission": "usuario comum",
@@ -264,7 +270,7 @@
       ],
       "behavior": {
         "type": "subcommand",
-        "allowed_actions": ["figurinhas", "sticker", "stickers", "midia", "media", "quote", "quotes", "ia", "ai", "stats", "estatisticas", "anime"]
+        "allowed_actions": ["top", "todos", "categoria", "figurinhas", "sticker", "stickers", "midia", "media", "quote", "quotes", "ia", "ai", "stats", "estatisticas", "anime"]
       },
       "limits": {
         "usage_description": "sem limite especifico",
@@ -357,6 +363,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "menu",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Exibe um menu dinâmico com comandos em destaque por uso, navegação por categoria e acesso ao catálogo completo do site.",
+        "quando_usar": ["Quando quiser descobrir os comandos mais usados sem receber uma lista gigante.", "Quando precisar navegar por comandos de uma categoria específica.", "Quando quiser abrir rapidamente o catálogo completo no site."],
+        "exemplos_reais": [
+          {
+            "situacao": "Usuário quer ver os comandos mais usados.",
+            "comando": "<prefix>menu top",
+            "resposta_esperada": "Lista com comandos em destaque por uso recente.",
+            "variacao": "ranking por uso"
+          },
+          {
+            "situacao": "Usuário quer comandos da categoria admin.",
+            "comando": "<prefix>menu categoria admin",
+            "resposta_esperada": "Lista de comandos da categoria solicitada.",
+            "variacao": "filtro por categoria"
+          },
+          {
+            "situacao": "Usuário quer ver o catálogo completo.",
+            "comando": "<prefix>menu todos",
+            "resposta_esperada": "Visão completa dos comandos por categoria e link do site.",
+            "variacao": "catálogo completo"
+          }
+        ],
+        "resposta_esperada": ["Menu carregado com as opções disponíveis.", "Menu da categoria exibido com opções correspondentes.", "Menu de estatísticas exibido com opções relevantes."],
+        "erros_comuns_usuario": ["Formato de uso incorreto. Use <prefix>menu ou <prefix>menu <categoria>.", "Categoria digitada não existe ou está incorreta.", "Não estar logado com Google quando o comando exigir autenticação.", "Digitar espaços extras ou caracteres não suportados na sintaxe do comando."],
+        "passos_se_der_erro": ["Verifique o formato: <prefix>menu ou <prefix>menu <categoria>.", "Confirme se a categoria informada existe entre as opções válidas.", "Assegure-se de estar logado com Google, se necessário.", "Tente novamente; se persistir, envie uma captura de tela do erro para apoio."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],