kasy-cli 1.8.2 → 1.9.0

package/bin/kasy.js

@@ -107,14 +107,55 @@ function createLocalizedHelpConfig(t) {
         }
       }
 
-      const commandList = helper.visibleCommands(cmd).map((subcommand) => {
-        return formatItem(
-          localizeSubcommandTerm(helper.subcommandTerm(subcommand)),
-          helper.subcommandDescription(subcommand)
-        );
-      });
-      if (commandList.length > 0) {
-        output = output.concat([`${t('cli.help.heading.commands')}:`, formatList(commandList), '']);
+      const visibleCommands = helper.visibleCommands(cmd);
+      if (visibleCommands.length > 0) {
+        const isRoot = cmd.parent === null || cmd.parent === undefined;
+        if (isRoot) {
+          // Group root commands by intent for easier scanning by non-devs.
+          const groups = [
+            { id: 'start',       ids: ['new', 'doctor', 'features'] },
+            { id: 'work',        ids: ['add', 'remove', 'update', 'run'] },
+            { id: 'publish',     ids: ['deploy', 'check', 'ios', 'codemagic'] },
+            { id: 'maintenance', ids: ['upgrade', 'version', 'uninstall', 'docs', 'notifications'] },
+            { id: 'advanced',    ids: ['setup', 'validate'] },
+          ];
+          const knownIds = new Set(groups.flatMap((g) => g.ids));
+          const byName = new Map(visibleCommands.map((c) => [c.name(), c]));
+          for (const group of groups) {
+            const items = group.ids
+              .map((id) => byName.get(id))
+              .filter(Boolean)
+              .map((sub) =>
+                formatItem(
+                  localizeSubcommandTerm(helper.subcommandTerm(sub)),
+                  helper.subcommandDescription(sub)
+                )
+              );
+            if (items.length === 0) continue;
+            output = output.concat([`${t(`cli.help.group.${group.id}`)}:`, formatList(items), '']);
+          }
+          const otherItems = visibleCommands
+            .filter((c) => !knownIds.has(c.name()))
+            .map((sub) =>
+              formatItem(
+                localizeSubcommandTerm(helper.subcommandTerm(sub)),
+                helper.subcommandDescription(sub)
+              )
+            );
+          if (otherItems.length > 0) {
+            output = output.concat([`${t('cli.help.group.other')}:`, formatList(otherItems), '']);
+          }
+          output = output.concat([helper.wrap(t('cli.help.tip'), helpWidth, 0), '']);
+        } else {
+          // Subcommand help — keep the flat list (no grouping).
+          const commandList = visibleCommands.map((subcommand) =>
+            formatItem(
+              localizeSubcommandTerm(helper.subcommandTerm(subcommand)),
+              helper.subcommandDescription(subcommand)
+            )
+          );
+          output = output.concat([`${t('cli.help.heading.commands')}:`, formatList(commandList), '']);
+        }
       }
 
       return output.join('\n');

package/lib/utils/i18n.js

@@ -22,8 +22,15 @@ const MESSAGES = {
     'cli.help.heading.options': 'Options',
     'cli.help.heading.globalOptions': 'Global Options',
     'cli.help.heading.commands': 'Commands',
-    'cli.command.setup.description': '📱 Set up a new Flutter app template',
-    'cli.command.new.description': '✨ Create a new app',
+    'cli.help.group.start': '🚀 Get started',
+    'cli.help.group.work': '🛠 Work on your app',
+    'cli.help.group.publish': '📤 Publish & test',
+    'cli.help.group.maintenance': '⚙️ Kasy CLI maintenance',
+    'cli.help.group.advanced': '🔧 Advanced',
+    'cli.help.group.other': 'Other',
+    'cli.help.tip': 'Tip: run `kasy <command> --help` for details. Use --lang pt|en|es to switch language.',
+    'cli.command.setup.description': '📱 (advanced) Set up an existing Flutter project',
+    'cli.command.new.description': '✨ Create a new app (e.g.: kasy new my-app)',
     'cli.command.new.projectName': 'project name',
     'cli.command.new.projectNameArg': 'Project folder name',
     'prompt.projectName.enter': "What's your project name?",
@@ -36,13 +43,13 @@ const MESSAGES = {
     'cli.command.setup.backendOption': 'Backend adapter (firebase, supabase, api)',
     'cli.command.setup.featuresOption': 'Comma separated optional features (web,widget,llm_chat,revenuecat,ci)',
     'cli.command.help.paramName': 'command',
-    'cli.command.doctor.description': '🩺 Check environment and dependencies',
-    'cli.command.modules.description': '🧩 List available backend and features',
-    'cli.command.validate.description': '✅ Validate minimum backend/feature combinations',
+    'cli.command.doctor.description': '🩺 Check if your computer is ready to run Kasy',
+    'cli.command.modules.description': '🧩 Show what comes included and what you can add',
+    'cli.command.validate.description': '✅ (advanced) Validate backend + feature combinations',
     'cli.command.validate.analyzeOnlyOption': 'Run flutter analyze only (skip builds)',
-    'cli.command.version.description': '🏷️ Print installed CLI version',
-    'cli.command.upgrade.description': '⬆️  Update the kasy CLI to the latest version',
-    'cli.command.uninstall.description': '🗑️  Uninstall the kasy CLI from this machine',
+    'cli.command.version.description': '🏷️ Show the installed Kasy version',
+    'cli.command.upgrade.description': '⬆️ Update the Kasy CLI to the latest version',
+    'cli.command.uninstall.description': '🗑️ Uninstall Kasy from this computer',
     'cli.command.upgrade.running': 'Updating kasy CLI...',
     'cli.command.upgrade.done': 'kasy updated successfully!',
     'cli.command.uninstall.running': 'Uninstalling kasy CLI...',
@@ -264,20 +271,20 @@ const MESSAGES = {
 
     'new.firebase.success.deployStep': '• Deploy backend (from inside the project folder):',
 
-    'cli.command.deploy.description': 'Deploy backend (Firebase or Supabase) — auto-detects project and configures FCM',
-    'cli.command.check.description': '🔔 Check push notifications setup (use --fix to auto-configure)',
+    'cli.command.deploy.description': '📤 Publish the server to Firebase or Supabase',
+    'cli.command.check.description': '🔔 Check push notifications setup (use --fix to fix it)',
     'deploy.q.project': 'Firebase Project ID:',
     'deploy.q.serviceAccount': 'Path to service account JSON:',
     'deploy.detected.project': '✓ Firebase project detected:',
     'deploy.detected.serviceAccount': '✓ Service account detected:',
     'deploy.error.notProject': 'No firebase.json found in this directory. Run kasy deploy from inside the project folder.',
 
-    'cli.command.ios.description': 'iOS App Store release (Mac)',
+    'cli.command.ios.description': '🍎 Publish the app to the App Store (Mac needed)',
     'cli.command.ios.configure.description': 'Configure Apple API credentials for local IPA upload',
     'cli.command.ios.release.description': 'Bump build, create IPA, and upload to App Store Connect',
     'cli.command.ios.build.description': 'Build IPA only (no upload)',
     'cli.command.ios.clean.description': 'Clean Flutter/Xcode caches before a failed iOS build',
-    'cli.command.codemagic.description': 'Trigger iOS builds on Codemagic (cloud)',
+    'cli.command.codemagic.description': '☁️ Build the app in the cloud (no Mac needed)',
     'cli.command.codemagic.configure.description': 'Configure Codemagic API credentials',
     'cli.command.codemagic.release.description': 'Start a Codemagic iOS workflow build',
     'cli.command.codemagic.status.description': 'Show Codemagic build status by ID',
@@ -594,7 +601,7 @@ const MESSAGES = {
     'new.internet.warning': '📶  Make sure you have a stable internet connection — this step requires network access.',
 
     // run command
-    'cli.command.run.description': '▶ Run the Flutter app using .env (launch.json dart-defines fallback)',
+    'cli.command.run.description': '▶ Run your app on phone, simulator, or browser',
     'run.launching': 'Launching Flutter app...',
     'run.updateHint.prefix': 'Project improvements available —',
     'run.updateHint.suffix': 'to see what\'s new',
@@ -612,13 +619,13 @@ const MESSAGES = {
     'doctor.project.noModules': 'No optional features active',
 
     // add command
-    'cli.command.add.description': '➕ Add a feature to an existing project',
+    'cli.command.add.description': '➕ Add a new feature to your app (e.g.: kasy add ai_chat)',
 
     // docs command
-    'cli.command.docs.description': '📖 Show CLI documentation and available commands',
+    'cli.command.docs.description': '📖 Open the full documentation',
 
     // notifications command
-    'cli.command.notifications.description': '🔔 Local notification copy (scheduled reminders + Home demo)',
+    'cli.command.notifications.description': '🔔 Edit the text of local notifications and reminders',
     'cli.command.notifications.text.description': 'Set titles and bodies shown in local notifications',
     'notifications.error.notKasyProject': 'No kit_setup.json found. Run this command from inside a Kasy project.',
     'notifications.error.noI18n': 'lib/i18n/*.i18n.json not found in this project.',
@@ -682,7 +689,7 @@ const MESSAGES = {
     'add.llm_chat.nextSteps.supabase': '\n  Next steps:\n  1. The LLM_CHAT_ENDPOINT in .vscode/launch.json has been pre-filled.\n  2. Run the app: kasy run\n',
     'add.llm_chat.nextSteps.supabase.deployFailed': '\n  Next steps:\n  1. Deploy manually: supabase functions deploy llm-chat --no-verify-jwt\n  2. The LLM_CHAT_ENDPOINT in .vscode/launch.json has been pre-filled.\n  3. Run the app: kasy run\n',
     'add.llm_chat.nextSteps.api': '\n  Next steps:\n  1. Create an endpoint on your server that accepts {message, history} and calls your LLM.\n  2. Update LLM_CHAT_ENDPOINT in .vscode/launch.json with your endpoint URL.\n  3. Run the app: kasy run\n',
-    'cli.command.remove.description': '🗑️  Remove a feature from an existing project',
+    'cli.command.remove.description': '🗑️ Remove a feature you no longer use (e.g.: kasy remove sentry)',
     'remove.error.noModule': 'Provide a feature name. Usage: kasy remove <feature>',
     'remove.error.notKasyProject': 'No kit_setup.json found. Run this command from inside a Kasy project.',
     'remove.error.unknownModule': 'Unknown feature: {module}\nAvailable: {list}',
@@ -699,7 +706,7 @@ const MESSAGES = {
     'remove.success': 'Feature "{module}" removed successfully.',
     'remove.warn.ci': 'CI files removed. If you had custom workflow files, restore them from git.',
     'remove.warn.sentry.shared': 'sentry_flutter kept — still required by active features (revenuecat/facebook).',
-    'cli.command.update.description': '⬆️  Update features/components in an existing project',
+    'cli.command.update.description': '⬆️ Update parts of your app to the latest (e.g.: kasy update components)',
     'cli.command.update.targetArg': 'Target to update (e.g. revenuecat, sentry, components)',
     'update.error.noProject': 'No kit_setup.json found. Run this command from inside a Kasy project.',
     'update.error.unknownModule': 'Unknown feature: {module}\nAvailable: {list}',
@@ -742,40 +749,47 @@ const MESSAGES = {
     'cli.tagline': 'Crie apps móveis sem dor de configuração',
     'cli.description': 'Crie apps Flutter sem dor de configuração.',
     'cli.usage': '<comando> [argumentos]',
-    'cli.option.version': 'Mostrar versao instalada',
+    'cli.option.version': 'Mostrar versão instalada',
     'cli.option.lang': 'Idioma (en, pt, es)',
     'cli.help.afterError': '(execute com --help para detalhes de uso)',
-    'cli.help.more': 'Execute "{command}" para detalhes de um comando especifico.',
+    'cli.help.more': 'Execute "{command}" para detalhes de um comando específico.',
     'cli.help.quickStart': 'Criar um novo app:',
     'cli.help.optionDescription': 'Mostrar ajuda do comando',
     'cli.help.commandDescription': 'Mostrar ajuda do comando',
-    'cli.help.inline.options': '[opcoes]',
+    'cli.help.inline.options': '[opções]',
     'cli.help.heading.usage': 'Uso',
     'cli.help.heading.arguments': 'Argumentos',
-    'cli.help.heading.options': 'Opcoes',
-    'cli.help.heading.globalOptions': 'Opcoes Globais',
+    'cli.help.heading.options': 'Opções',
+    'cli.help.heading.globalOptions': 'Opções globais',
     'cli.help.heading.commands': 'Comandos',
-    'cli.command.setup.description': '📱 Configura um novo template Flutter',
-    'cli.command.new.description': '✨ Cria um novo app',
+    'cli.help.group.start': '🚀 Para começar',
+    'cli.help.group.work': '🛠 Trabalhar no app',
+    'cli.help.group.publish': '📤 Publicar e testar',
+    'cli.help.group.maintenance': '⚙️ Manutenção da Kasy CLI',
+    'cli.help.group.advanced': '🔧 Avançado',
+    'cli.help.group.other': 'Outros',
+    'cli.help.tip': 'Dica: rode `kasy <comando> --help` para detalhes. Use --lang pt|en|es para mudar o idioma.',
+    'cli.command.setup.description': '📱 (avançado) Configura um projeto Flutter existente',
+    'cli.command.new.description': '✨ Cria um app novo (ex: kasy new meu-app)',
     'cli.command.new.projectName': 'nome do projeto',
     'cli.command.new.projectNameArg': 'Nome da pasta do projeto',
     'prompt.projectName.enter': 'Qual o nome do seu projeto?',
     'prompt.projectName.required': 'O nome do projeto é obrigatório.',
     'prompt.projectName.default': 'meu_app',
-    'cli.command.setup.directoryName': 'diretorio',
+    'cli.command.setup.directoryName': 'diretório',
     'cli.command.setup.directoryArg': 'Diretório de destino (padrão: pasta atual .)',
     'cli.command.setup.langName': 'idioma',
     'cli.command.setup.langOption': 'Idioma dos prompts (en, pt, es)',
     'cli.command.setup.backendOption': 'Adapter de backend (firebase, supabase, api)',
     'cli.command.setup.featuresOption': 'Features opcionais separadas por virgula (web,widget,llm_chat,revenuecat,ci)',
     'cli.command.help.paramName': 'comando',
-    'cli.command.doctor.description': '🩺 Verifica ambiente e dependencias',
-    'cli.command.modules.description': '🧩 Lista backends e features disponiveis',
-    'cli.command.validate.description': '✅ Valida combinacoes minimas de backend/features',
+    'cli.command.doctor.description': '🩺 Verifica se o seu computador está pronto para rodar a Kasy',
+    'cli.command.modules.description': '🧩 Mostra o que já vem incluso e o que você pode adicionar',
+    'cli.command.validate.description': '✅ (avançado) Valida combinações de backend e features',
     'cli.command.validate.analyzeOnlyOption': 'Executa apenas flutter analyze (sem build)',
-    'cli.command.version.description': '🏷️ Mostra a versao instalada da CLI',
-    'cli.command.upgrade.description': '⬆️  Atualiza a CLI kasy para a versao mais recente',
-    'cli.command.uninstall.description': '🗑️  Remove a CLI kasy desta maquina',
+    'cli.command.version.description': '🏷️ Mostra a versão instalada da Kasy',
+    'cli.command.upgrade.description': '⬆️ Atualiza a Kasy CLI para a versão mais recente',
+    'cli.command.uninstall.description': '🗑️ Desinstala a Kasy deste computador',
     'cli.command.upgrade.running': 'Atualizando a CLI kasy...',
     'cli.command.upgrade.done': 'kasy atualizado com sucesso!',
     'cli.command.uninstall.running': 'Desinstalando a CLI kasy...',
@@ -997,20 +1011,20 @@ const MESSAGES = {
 
     'new.firebase.success.deployStep': '• Deploy do backend (de dentro da pasta do projeto):',
 
-    'cli.command.deploy.description': 'Deploy do backend (Firebase ou Supabase) — detecta projeto e configura FCM',
-    'cli.command.check.description': '🔔 Verifica configuração de push notifications (use --fix para corrigir)',
+    'cli.command.deploy.description': '📤 Publica o servidor no Firebase ou Supabase',
+    'cli.command.check.description': '🔔 Confere se as notificações push estão configuradas (use --fix para corrigir)',
     'deploy.q.project': 'Firebase Project ID:',
     'deploy.q.serviceAccount': 'Caminho para o service account JSON:',
     'deploy.detected.project': '✓ Projeto Firebase detectado:',
     'deploy.detected.serviceAccount': '✓ Service account detectado:',
     'deploy.error.notProject': 'Nenhum firebase.json encontrado. Execute kasy deploy de dentro da pasta do projeto.',
 
-    'cli.command.ios.description': 'Release iOS na App Store (Mac)',
+    'cli.command.ios.description': '🍎 Publica o app na App Store (precisa de Mac)',
     'cli.command.ios.configure.description': 'Configurar credenciais Apple para envio local do IPA',
     'cli.command.ios.release.description': 'Incrementa build, gera IPA e envia para App Store Connect',
     'cli.command.ios.build.description': 'Só gera o IPA (sem enviar)',
     'cli.command.ios.clean.description': 'Limpa caches Flutter/Xcode após falha no build iOS',
-    'cli.command.codemagic.description': 'Disparar build iOS no Codemagic (nuvem)',
+    'cli.command.codemagic.description': '☁️ Compila o app na nuvem (sem precisar de Mac)',
     'cli.command.codemagic.configure.description': 'Configurar credenciais da API Codemagic',
     'cli.command.codemagic.release.description': 'Iniciar build do workflow iOS no Codemagic',
     'cli.command.codemagic.status.description': 'Status do build Codemagic por ID',
@@ -1327,7 +1341,7 @@ const MESSAGES = {
     'new.internet.warning': '📶  Verifique se voce esta com uma internet estavel — esta etapa precisa de conexao.',
 
     // run command
-    'cli.command.run.description': '▶ Executa o app Flutter usando .env (fallback para dart-defines do launch.json)',
+    'cli.command.run.description': '▶ Roda o app no celular, simulador ou navegador',
     'run.launching': 'Iniciando app Flutter...',
     'run.updateHint.prefix': 'Melhorias disponíveis para o projeto —',
     'run.updateHint.suffix': 'para ver o que há de novo',
@@ -1345,13 +1359,13 @@ const MESSAGES = {
     'doctor.project.noModules': 'Nenhuma feature opcional ativa',
 
     // add command
-    'cli.command.add.description': '➕ Adiciona uma feature a um projeto existente',
+    'cli.command.add.description': '➕ Adiciona algo novo ao app (ex: kasy add ai_chat)',
 
     // docs command
-    'cli.command.docs.description': '📖 Exibe a documentacao e comandos disponiveis',
+    'cli.command.docs.description': '📖 Abre a documentação completa',
 
     // notifications command
-    'cli.command.notifications.description': '🔔 Textos de notificacao local (lembretes + demo na Home)',
+    'cli.command.notifications.description': '🔔 Edita os textos das notificações locais e lembretes',
     'cli.command.notifications.text.description': 'Define titulos e mensagens das notificacoes locais',
     'notifications.error.notKasyProject': 'kit_setup.json nao encontrado. Execute dentro de um projeto Kasy.',
     'notifications.error.noI18n': 'lib/i18n/*.i18n.json nao encontrado neste projeto.',
@@ -1415,7 +1429,7 @@ const MESSAGES = {
     'add.llm_chat.nextSteps.supabase': '\n  Proximos passos:\n  1. O LLM_CHAT_ENDPOINT no .vscode/launch.json ja foi preenchido.\n  2. Rode o app: kasy run\n',
     'add.llm_chat.nextSteps.supabase.deployFailed': '\n  Proximos passos:\n  1. Deploy manual: supabase functions deploy llm-chat --no-verify-jwt\n  2. O LLM_CHAT_ENDPOINT no .vscode/launch.json ja foi preenchido.\n  3. Rode o app: kasy run\n',
     'add.llm_chat.nextSteps.api': '\n  Proximos passos:\n  1. Crie um endpoint no seu servidor que aceite {message, history} e chame sua LLM.\n  2. Atualize LLM_CHAT_ENDPOINT no .vscode/launch.json com a URL do seu endpoint.\n  3. Rode o app: kasy run\n',
-    'cli.command.remove.description': '🗑️  Remove uma feature de um projeto existente',
+    'cli.command.remove.description': '🗑️ Remove algo que você não usa mais (ex: kasy remove sentry)',
     'remove.error.noModule': 'Informe o nome da feature. Uso: kasy remove <feature>',
     'remove.error.notKasyProject': 'kit_setup.json nao encontrado. Execute este comando dentro de um projeto Kasy.',
     'remove.error.unknownModule': 'Feature desconhecida: {module}\nDisponiveis: {list}',
@@ -1432,7 +1446,7 @@ const MESSAGES = {
     'remove.success': 'Feature "{module}" removida com sucesso.',
     'remove.warn.ci': 'Arquivos de CI removidos. Se tinha workflows customizados, restaure-os pelo git.',
     'remove.warn.sentry.shared': 'sentry_flutter mantido — ainda necessario para features ativas (revenuecat/facebook).',
-    'cli.command.update.description': '⬆️  Atualiza features/componentes em um projeto existente',
+    'cli.command.update.description': '⬆️ Atualiza partes do app para a última versão (ex: kasy update components)',
     'cli.command.update.targetArg': 'Alvo para atualizar (ex.: revenuecat, sentry, components)',
     'update.error.noProject': 'kit_setup.json nao encontrado. Execute dentro de um projeto Kasy.',
     'update.error.unknownModule': 'Modulo desconhecido: {module}\nDisponiveis: {list}',
@@ -1475,10 +1489,10 @@ const MESSAGES = {
     'cli.tagline': 'Crea apps móviles sin dolor de configuración',
     'cli.description': 'Crea apps Flutter sin dolor de configuración.',
     'cli.usage': '<comando> [argumentos]',
-    'cli.option.version': 'Mostrar version instalada',
+    'cli.option.version': 'Mostrar versión instalada',
     'cli.option.lang': 'Idioma (en, pt, es)',
     'cli.help.afterError': '(ejecuta con --help para detalles de uso)',
-    'cli.help.more': 'Ejecuta "{command}" para detalles de un comando especifico.',
+    'cli.help.more': 'Ejecuta "{command}" para detalles de un comando específico.',
     'cli.help.quickStart': 'Crear un nuevo app:',
     'cli.help.optionDescription': 'Mostrar ayuda del comando',
     'cli.help.commandDescription': 'Mostrar ayuda del comando',
@@ -1486,10 +1500,17 @@ const MESSAGES = {
     'cli.help.heading.usage': 'Uso',
     'cli.help.heading.arguments': 'Argumentos',
     'cli.help.heading.options': 'Opciones',
-    'cli.help.heading.globalOptions': 'Opciones Globales',
+    'cli.help.heading.globalOptions': 'Opciones globales',
     'cli.help.heading.commands': 'Comandos',
-    'cli.command.setup.description': '📱 Configura una nueva plantilla Flutter',
-    'cli.command.new.description': '✨ Crea un nuevo app',
+    'cli.help.group.start': '🚀 Para empezar',
+    'cli.help.group.work': '🛠 Trabajar en tu app',
+    'cli.help.group.publish': '📤 Publicar y probar',
+    'cli.help.group.maintenance': '⚙️ Mantenimiento de Kasy CLI',
+    'cli.help.group.advanced': '🔧 Avanzado',
+    'cli.help.group.other': 'Otros',
+    'cli.help.tip': 'Tip: ejecuta `kasy <comando> --help` para más detalles. Usa --lang pt|en|es para cambiar idioma.',
+    'cli.command.setup.description': '📱 (avanzado) Configura un proyecto Flutter existente',
+    'cli.command.new.description': '✨ Crea una app nueva (ej: kasy new mi-app)',
     'cli.command.new.projectName': 'nombre del proyecto',
     'cli.command.new.projectNameArg': 'Nombre de la carpeta del proyecto',
     'prompt.projectName.enter': '¿Cuál es el nombre de tu proyecto?',
@@ -1502,13 +1523,13 @@ const MESSAGES = {
     'cli.command.setup.backendOption': 'Adapter de backend (firebase, supabase, api)',
     'cli.command.setup.featuresOption': 'Features opcionales separadas por coma (web,widget,llm_chat,revenuecat,ci)',
     'cli.command.help.paramName': 'comando',
-    'cli.command.doctor.description': '🩺 Verifica entorno y dependencias',
-    'cli.command.modules.description': '🧩 Lista backends y features disponibles',
-    'cli.command.validate.description': '✅ Valida combinaciones minimas de backend/features',
+    'cli.command.doctor.description': '🩺 Verifica si tu computadora está lista para correr Kasy',
+    'cli.command.modules.description': '🧩 Muestra lo que viene incluido y lo que puedes añadir',
+    'cli.command.validate.description': '✅ (avanzado) Valida combinaciones de backend y features',
     'cli.command.validate.analyzeOnlyOption': 'Ejecuta solo flutter analyze (sin build)',
-    'cli.command.version.description': '🏷️ Muestra la version instalada de la CLI',
-    'cli.command.upgrade.description': '⬆️  Actualiza la CLI kasy a la ultima version',
-    'cli.command.uninstall.description': '🗑️  Desinstala la CLI kasy de esta maquina',
+    'cli.command.version.description': '🏷️ Muestra la versión instalada de Kasy',
+    'cli.command.upgrade.description': '⬆️ Actualiza la Kasy CLI a la última versión',
+    'cli.command.uninstall.description': '🗑️ Desinstala Kasy de esta computadora',
     'cli.command.upgrade.running': 'Actualizando la CLI kasy...',
     'cli.command.upgrade.done': 'kasy actualizado correctamente!',
     'cli.command.uninstall.running': 'Desinstalando la CLI kasy...',
@@ -1732,20 +1753,20 @@ const MESSAGES = {
 
     'new.firebase.success.deployStep': '• Desplegar backend (desde dentro de la carpeta del proyecto):',
 
-    'cli.command.deploy.description': 'Despliega el backend (Firebase o Supabase) — detecta proyecto y configura FCM',
-    'cli.command.check.description': '🔔 Verifica configuración de push notifications (usa --fix para corregir)',
+    'cli.command.deploy.description': '📤 Publica el servidor en Firebase o Supabase',
+    'cli.command.check.description': '🔔 Verifica si las notificaciones push están configuradas (usa --fix para arreglar)',
     'deploy.q.project': 'Firebase Project ID:',
     'deploy.q.serviceAccount': 'Ruta al service account JSON:',
     'deploy.detected.project': '✓ Proyecto Firebase detectado:',
     'deploy.detected.serviceAccount': '✓ Service account detectado:',
     'deploy.error.notProject': 'No se encontro firebase.json. Ejecute kasy deploy desde dentro de la carpeta del proyecto.',
 
-    'cli.command.ios.description': 'Release iOS en App Store (Mac)',
+    'cli.command.ios.description': '🍎 Publica la app en la App Store (necesita Mac)',
     'cli.command.ios.configure.description': 'Configurar credenciales Apple para subida local del IPA',
     'cli.command.ios.release.description': 'Incrementa build, genera IPA y sube a App Store Connect',
     'cli.command.ios.build.description': 'Solo genera el IPA (sin subir)',
     'cli.command.ios.clean.description': 'Limpia cachés Flutter/Xcode tras fallo en build iOS',
-    'cli.command.codemagic.description': 'Disparar build iOS en Codemagic (nube)',
+    'cli.command.codemagic.description': '☁️ Compila la app en la nube (sin necesitar Mac)',
     'cli.command.codemagic.configure.description': 'Configurar credenciales API de Codemagic',
     'cli.command.codemagic.release.description': 'Iniciar build del workflow iOS en Codemagic',
     'cli.command.codemagic.status.description': 'Estado del build Codemagic por ID',
@@ -2060,7 +2081,7 @@ const MESSAGES = {
     'new.internet.warning': '📶  Asegurate de tener una conexion a internet estable — este paso requiere red.',
 
     // run command
-    'cli.command.run.description': '▶ Ejecuta el app Flutter usando .env (fallback a dart-defines del launch.json)',
+    'cli.command.run.description': '▶ Corre la app en celular, simulador o navegador',
     'run.launching': 'Iniciando app Flutter...',
     'run.updateHint.prefix': 'Mejoras disponibles para el proyecto —',
     'run.updateHint.suffix': 'para ver las novedades',
@@ -2078,13 +2099,13 @@ const MESSAGES = {
     'doctor.project.noModules': 'Ninguna feature opcional activa',
 
     // add command
-    'cli.command.add.description': '➕ Agrega una feature a un proyecto existente',
+    'cli.command.add.description': '➕ Añade algo nuevo a tu app (ej: kasy add ai_chat)',
 
     // docs command
-    'cli.command.docs.description': '📖 Muestra la documentacion y comandos disponibles',
+    'cli.command.docs.description': '📖 Abre la documentación completa',
 
     // notifications command
-    'cli.command.notifications.description': '🔔 Textos de notificacion local (recordatorios + demo en Home)',
+    'cli.command.notifications.description': '🔔 Edita los textos de las notificaciones locales y recordatorios',
     'cli.command.notifications.text.description': 'Define titulos y mensajes de notificaciones locales',
     'notifications.error.notKasyProject': 'No se encontro kit_setup.json. Ejecuta dentro de un proyecto Kasy.',
     'notifications.error.noI18n': 'lib/i18n/*.i18n.json no encontrado en este proyecto.',
@@ -2148,7 +2169,7 @@ const MESSAGES = {
     'add.llm_chat.nextSteps.supabase': '\n  Proximos pasos:\n  1. El LLM_CHAT_ENDPOINT en .vscode/launch.json ya fue pre-llenado.\n  2. Corre el app: kasy run\n',
     'add.llm_chat.nextSteps.supabase.deployFailed': '\n  Proximos pasos:\n  1. Deploy manual: supabase functions deploy llm-chat --no-verify-jwt\n  2. El LLM_CHAT_ENDPOINT en .vscode/launch.json ya fue pre-llenado.\n  3. Corre el app: kasy run\n',
     'add.llm_chat.nextSteps.api': '\n  Proximos pasos:\n  1. Crea un endpoint en tu servidor que acepte {message, history} y llame tu LLM.\n  2. Actualiza LLM_CHAT_ENDPOINT en .vscode/launch.json con la URL de tu endpoint.\n  3. Corre el app: kasy run\n',
-    'cli.command.remove.description': '🗑️  Elimina una feature de un proyecto existente',
+    'cli.command.remove.description': '🗑️ Elimina algo que ya no usas (ej: kasy remove sentry)',
     'remove.error.noModule': 'Ingresa el nombre de la feature. Uso: kasy remove <feature>',
     'remove.error.notKasyProject': 'kit_setup.json no encontrado. Ejecuta este comando dentro de un proyecto Kasy.',
     'remove.error.unknownModule': 'Modulo desconocido: {module}\nDisponibles: {list}',
@@ -2165,7 +2186,7 @@ const MESSAGES = {
     'remove.success': 'Feature "{module}" eliminada exitosamente.',
     'remove.warn.ci': 'Archivos de CI eliminados. Si tenias workflows personalizados, restauralos desde git.',
     'remove.warn.sentry.shared': 'sentry_flutter conservado — todavia requerido por features activas (revenuecat/facebook).',
-    'cli.command.update.description': '⬆️  Actualiza features/componentes en un proyecto existente',
+    'cli.command.update.description': '⬆️ Actualiza partes de tu app a la última versión (ej: kasy update components)',
     'cli.command.update.targetArg': 'Objetivo a actualizar (ej.: revenuecat, sentry, components)',
     'update.error.noProject': 'kit_setup.json no encontrado. Ejecuta dentro de un proyecto Kasy.',
     'update.error.unknownModule': 'Modulo desconocido: {module}\nDisponibles: {list}',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "CLI for scaffolding production-ready Flutter SaaS apps with Firebase, Supabase, or API REST backends.",
   "bin": {
     "kasy": "./bin/kasy.js"

package/templates/firebase/lib/core/guards/user_info_guard.dart

@@ -2,6 +2,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/core/config/features.dart';
+import 'package:kasy_kit/core/data/models/user.dart';
 import 'package:kasy_kit/core/guards/guard.dart';
 import 'package:kasy_kit/core/states/user_state_notifier.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
@@ -44,9 +45,14 @@ class UserInfosGuard extends ConsumerWidget {
     // Native: all users (including guests with no ID) go through onboarding.
     // Guests are never forced to /signin here; individual features that
     // require authentication redirect to /signin on their own.
+    // Authenticated users skip onboarding: they already committed to an account
+    // (e.g. returning user signing back in after the anonymous session was
+    // discarded by `credential-already-in-use`).
     return Guard(
       canActivate: Future.value(
-        !withOnboarding || authState.user.isOnboarded,
+        !withOnboarding ||
+            authState.user.isOnboarded ||
+            authState.user is AuthenticatedUserData,
       ),
       fallbackRoute: fallbackRoute,
       child: child,

package/templates/firebase/lib/features/notifications/api/notifications_api.dart

@@ -1,6 +1,7 @@
 import 'package:cloud_firestore/cloud_firestore.dart';
 import 'package:cloud_functions/cloud_functions.dart';
 import 'package:firebase_messaging/firebase_messaging.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/core/data/api/base_api_exceptions.dart';
 import 'package:kasy_kit/features/notifications/api/entities/notifications_entity.dart';
@@ -224,6 +225,12 @@ class FirebaseNotificationsApi implements NotificationsApi {
       try {
         final agg = await query.count().get();
         yield agg.count ?? 0;
+      } on FirebaseException catch (e) {
+        if (e.code == 'permission-denied') return;
+        _logger.e('unreadNotifications error: $e');
+      } on PlatformException catch (e) {
+        if (e.code == 'permission-denied') return;
+        _logger.e('unreadNotifications error: $e');
       } catch (e, s) {
         _logger.e('unreadNotifications error: $e: $s');
       }