@jaimevalasek/aioson 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/cli.js

@@ -229,6 +229,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'agents',
   'agent:prompt',
   'agent-prompt',
+  'agent:help',
+  'agent-help',
   'agent:invoke',
   'agent-invoke',
   'setup:context',
@@ -700,6 +702,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'system-install'
 ]);
 
+const AGENT_HELP_COMMANDS = new Set([
+  'agent:prompt', 'agent-prompt', 'agent:invoke', 'agent-invoke', 'agent:help', 'agent-help'
+]);
+
 const LEGACY_DASHBOARD_COMMANDS = new Set([
   'dashboard:init',
   'dashboard-init',
@@ -748,6 +754,7 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_i18n_add');
   logHelpLine(t, logger, 'cli.help_agents');
   logHelpLine(t, logger, 'cli.help_agent_prompt');
+  logHelpLine(t, logger, 'cli.help_agent_help');
   logHelpLine(t, logger, 'cli.help_agent_invoke');
   logHelpLine(t, logger, 'cli.help_context_validate');
   logHelpLine(t, logger, 'cli.help_context_pack');
@@ -851,6 +858,91 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_squad_grant');
 }
 
+function printAgentHelp(agentName, jsonMode, logger, t) {
+  const { AGENT_DEFINITIONS } = require('./constants');
+  const { normalizeAgentName } = require('./agents');
+
+  if (!agentName) {
+    const list = AGENT_DEFINITIONS.map((a) => ({
+      id: a.id,
+      displayName: a.displayName,
+      description: a.description || ''
+    }));
+    if (jsonMode) {
+      writeJson({ ok: true, agents: list });
+      return;
+    }
+    logger.log(`${t('agents.help_available')}\n`);
+    for (const a of list) {
+      logger.log(`  @${a.id.padEnd(24)} ${a.description}`);
+    }
+    logger.log(`\n${t('agents.help_run_detail')}`);
+    return;
+  }
+
+  const normalized = normalizeAgentName(agentName);
+  const agent = AGENT_DEFINITIONS.find((a) => {
+    if (a.id === normalized) return true;
+    return Array.isArray(a.aliases) && a.aliases.includes(normalized);
+  });
+
+  if (!agent) {
+    if (jsonMode) {
+      writeJson({ ok: false, error: t('agents.help_unknown_agent', { agent: agentName }) });
+    } else {
+      logger.error(t('agents.help_unknown_agent', { agent: agentName }));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (jsonMode) {
+    writeJson({
+      ok: true,
+      agent: {
+        id: agent.id,
+        displayName: agent.displayName,
+        description: agent.description || '',
+        command: agent.command,
+        path: agent.path,
+        aliases: agent.aliases || [],
+        flags: agent.flags || [],
+        dependsOn: agent.dependsOn,
+        output: agent.output
+      }
+    });
+    return;
+  }
+
+  const aliasLine = agent.aliases && agent.aliases.length > 0
+    ? ` (aliases: ${agent.aliases.join(', ')})`
+    : '';
+  logger.log(`${agent.command} — ${agent.description || agent.displayName}${aliasLine}\n`);
+  logger.log(`${t('agents.help_usage')}`);
+  logger.log(`  aioson agent:prompt ${agent.id} [path] [options]`);
+  logger.log(`  /${agent.id} [task description]                  ${t('agents.help_claude_code')}\n`);
+  logger.log(t('agents.help_common_options'));
+  logger.log(`  --tool=<tool>       ${t('agents.help_opt_tool')}`);
+  logger.log(`  --language=<lang>   ${t('agents.help_opt_language')}`);
+  logger.log(`  --headless          ${t('agents.help_opt_headless')}`);
+  logger.log(`  --output=<path>     ${t('agents.help_opt_output')}`);
+  logger.log(`  --json              ${t('agents.help_opt_json')}`);
+  if (agent.flags && agent.flags.length > 0) {
+    logger.log(`\n${t('agents.help_agent_options', { command: agent.command })}`);
+    for (const flag of agent.flags) {
+      logger.log(`  --${flag.name}=${flag.value.padEnd(Math.max(12 - flag.name.length, 1))} ${flag.description}`);
+    }
+  }
+  if (agent.dependsOn.length > 0) {
+    logger.log(`\n${t('agents.help_requires')}`);
+    for (const dep of agent.dependsOn) {
+      logger.log(`  ${dep}`);
+    }
+  }
+  logger.log(`\n${t('agents.help_produces')}\n  ${agent.output}`);
+  logger.log(`\n${t('agents.help_instruction_file')}\n  ${agent.path}`);
+}
+
 function commandSupportsJson(command) {
   return JSON_SUPPORTED_COMMANDS.has(command);
 }
@@ -868,19 +960,31 @@ async function main() {
   const logger = createLogger();
   const silentLogger = createSilentLogger();
 
-  if (command === 'help' || options.help || command === '--help' || command === '-h') {
-    printHelp(t, logger);
-    return;
-  }
-
   if (command === '--version' || command === '-v' || command === 'version' || options.version) {
-    const result = await runInfo({ args: ['.'], options, logger, t });
+    const { getCliVersionSync } = require('./version');
+    const version = getCliVersionSync();
     if (jsonMode) {
-      writeJson(result);
+      writeJson({ ok: true, version });
+    } else {
+      logger.log(`aioson ${version}`);
     }
     return;
   }
 
+  if (options.help && AGENT_HELP_COMMANDS.has(command)) {
+    printAgentHelp(args[0], jsonMode, logger, t);
+    return;
+  }
+  if (command === 'agent:help' || command === 'agent-help') {
+    printAgentHelp(args[0], jsonMode, logger, t);
+    return;
+  }
+
+  if (command === 'help' || options.help || command === '--help' || command === '-h') {
+    printHelp(t, logger);
+    return;
+  }
+
   if (LEGACY_DASHBOARD_COMMANDS.has(command)) {
     const message = t('cli.dashboard_moved', { command });
     if (jsonMode) {

package/src/constants.js

@@ -190,6 +190,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'setup',
     displayName: 'Setup',
+    description: 'Project onboarding and context setup',
     command: '@setup',
     path: '.aioson/agents/setup.md',
     dependsOn: [],
@@ -198,6 +199,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'discovery-design-doc',
     displayName: 'Discovery/Design Doc',
+    description: 'Discovery and design doc generation',
     command: '@discovery-design-doc',
     path: '.aioson/agents/discovery-design-doc.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -206,6 +208,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'discover',
     displayName: 'Discover',
+    description: 'Semantic knowledge discovery and bootstrap cache generation',
     command: '@discover',
     path: '.aioson/agents/discover.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -214,6 +217,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'product',
     displayName: 'Product',
+    description: 'Product vision, PRD and feature scoping',
     command: '@product',
     path: '.aioson/agents/product.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -222,6 +226,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'deyvin',
     displayName: 'Deyvin',
+    description: 'Pair programming partner for continuity sessions',
     command: '@deyvin',
     path: '.aioson/agents/deyvin.md',
     aliases: ['pair'],
@@ -231,6 +236,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'analyst',
     displayName: 'Analyst',
+    description: 'Domain discovery and entity mapping (SMALL/MEDIUM)',
     command: '@analyst',
     path: '.aioson/agents/analyst.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -239,6 +245,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'architect',
     displayName: 'Architect',
+    description: 'Project structure and technical decisions (SMALL/MEDIUM)',
     command: '@architect',
     path: '.aioson/agents/architect.md',
     dependsOn: [
@@ -250,6 +257,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'ux-ui',
     displayName: 'UI/UX',
+    description: 'UI/UX design system and component spec (SMALL/MEDIUM)',
     command: '@ux-ui',
     path: '.aioson/agents/ux-ui.md',
     dependsOn: [
@@ -263,6 +271,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'pm',
     displayName: 'PM',
+    description: 'Backlog and user stories (MEDIUM only)',
     command: '@pm',
     path: '.aioson/agents/pm.md',
     dependsOn: [
@@ -277,6 +286,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'dev',
     displayName: 'Dev',
+    description: 'Feature implementation (any stack)',
     command: '@dev',
     path: '.aioson/agents/dev.md',
     dependsOn: [
@@ -289,8 +299,14 @@ const AGENT_DEFINITIONS = [
   {
     id: 'pentester',
     displayName: 'Pentester',
+    description: 'Adversarial security review and threat-surface mapping',
     command: '@pentester',
     path: '.aioson/agents/pentester.md',
+    flags: [
+      { name: 'mode', value: 'framework_target|app_target', description: 'Target mode for security review' },
+      { name: 'feature', value: '<slug>', description: 'Feature slug (required for app_target)' },
+      { name: 'scope', value: '<scope>', description: 'Target scope (required for app_target)' }
+    ],
     dependsOn: [
       '.aioson/context/project.context.md',
       '.aioson/context/spec-{slug}.md (active feature)'
@@ -300,6 +316,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'qa',
     displayName: 'QA',
+    description: 'Risk-first review and test generation (SMALL/MEDIUM)',
     command: '@qa',
     path: '.aioson/agents/qa.md',
     dependsOn: ['.aioson/context/discovery.md'],
@@ -308,6 +325,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'validator',
     displayName: 'Validator',
+    description: 'Technical validation against success contract',
     command: '@validator',
     path: '.aioson/agents/validator.md',
     dependsOn: [
@@ -319,6 +337,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'tester',
     displayName: 'Tester',
+    description: 'Systematic test engineering for implemented apps (all sizes)',
     command: '@tester',
     path: '.aioson/agents/tester.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -327,6 +346,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'orchestrator',
     displayName: 'Orchestrator',
+    description: 'Session protocol and parallel execution (MEDIUM)',
     command: '@orchestrator',
     path: '.aioson/agents/orchestrator.md',
     dependsOn: [
@@ -342,6 +362,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'squad',
     displayName: 'Squad',
+    description: 'Squad assembly and management',
     command: '@squad',
     path: '.aioson/agents/squad.md',
     dependsOn: [],
@@ -351,6 +372,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'orache',
     displayName: 'Orache',
+    description: 'Domain investigation and strategic research',
     command: '@orache',
     path: '.aioson/agents/orache.md',
     dependsOn: [],
@@ -359,6 +381,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'genome',
     displayName: 'Genome',
+    description: 'Domain genome creation and application',
     command: '@genome',
     path: '.aioson/agents/genome.md',
     dependsOn: [],
@@ -367,6 +390,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'design-hybrid-forge',
     displayName: 'Design Hybrid Forge',
+    description: 'Generate hybrid design skill from two visual parents',
     command: '@design-hybrid-forge',
     path: '.aioson/agents/design-hybrid-forge.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -375,14 +399,61 @@ const AGENT_DEFINITIONS = [
   {
     id: 'site-forge',
     displayName: 'Site Forge',
+    description: 'Clone, extract, and forge sites and design skills from any URL',
     command: '@site-forge',
     path: '.aioson/agents/site-forge.md',
     dependsOn: ['.aioson/context/project.context.md'],
     output: 'src/components/*.tsx + src/app/page.tsx + docs/research/{hostname}/ + public/images/{hostname}/'
   },
+  {
+    id: 'neo',
+    displayName: 'Neo',
+    description: 'System router: see the full picture, get guided to the right agent',
+    command: '@neo',
+    path: '.aioson/agents/neo.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: 'routing decision + agent handoff'
+  },
+  {
+    id: 'sheldon',
+    displayName: 'Sheldon',
+    description: 'Deep technical analysis and architecture review',
+    command: '@sheldon',
+    path: '.aioson/agents/sheldon.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: 'enriched PRD or architecture review'
+  },
+  {
+    id: 'committer',
+    displayName: 'Committer',
+    description: 'Professional Git commit generation from changes and context',
+    command: '@committer',
+    path: '.aioson/agents/committer.md',
+    dependsOn: [],
+    output: 'git commit(s)'
+  },
+  {
+    id: 'copywriter',
+    displayName: 'Copywriter',
+    description: 'Conversion-focused marketing copy',
+    command: '@copywriter',
+    path: '.aioson/agents/copywriter.md',
+    dependsOn: [],
+    output: 'marketing copy + content assets'
+  },
+  {
+    id: 'briefing',
+    displayName: 'Briefing',
+    description: 'Pre-production briefings and planning',
+    command: '@briefing',
+    path: '.aioson/agents/briefing.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: '.aioson/briefings/{slug}/'
+  },
   {
     id: 'profiler-researcher',
     displayName: 'Profiler Researcher',
+    description: 'Clone profiler: research phase',
     command: '@profiler-researcher',
     path: '.aioson/agents/profiler-researcher.md',
     dependsOn: [],
@@ -391,6 +462,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'profiler-enricher',
     displayName: 'Profiler Enricher',
+    description: 'Clone profiler: enrichment phase',
     command: '@profiler-enricher',
     path: '.aioson/agents/profiler-enricher.md',
     dependsOn: ['.aioson/profiler-reports/{person-slug}/research-report.md'],
@@ -399,6 +471,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'profiler-forge',
     displayName: 'Profiler Forge',
+    description: 'Clone profiler: forge and validate',
     command: '@profiler-forge',
     path: '.aioson/agents/profiler-forge.md',
     dependsOn: ['.aioson/profiler-reports/{person-slug}/enriched-profile.md'],

package/src/i18n/messages/en.js

@@ -19,6 +19,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=en]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
@@ -219,7 +221,7 @@ module.exports = {
     help_runtime_emit:
       'aioson runtime:emit [path] --agent=<name> [--type=<event>] [--summary=<text>] [--title=<text>] [--refs=<file[,file2]>] [--plan-step=<id>] [--meta=<json>] [--json] [--locale=en]',
     help_live_start:
-      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<name> [--tool-bin=<binary>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--tmux] [--json] [--locale=en]',
+      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<name> [--tool-bin=<binary>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--tmux] [--json] [--locale=en]',
     help_live_status:
       'aioson live:status [path] [--agent=<name>] [--limit=8] [--watch=2] [--format=compact|tmux-bar] [--json] [--locale=en]',
     help_live_handoff:
@@ -505,7 +507,22 @@ module.exports = {
       'Pentester app_target requires --feature=<slug> (or --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target requires --scope=<area>.',
-    prompt_title: 'Prompt for agent "{agent}" on tool "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt for agent "{agent}" on tool "{tool}" (locale: {locale}):',
+    help_available: 'Available agents:',
+    help_run_detail: 'Run "aioson agent:help <name>" for details on a specific agent.',
+    help_usage: 'Usage:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Common options:',
+    help_opt_tool: 'Target tool (codex|claude|gemini|opencode)',
+    help_opt_language: 'Interaction language (e.g., pt-BR, en)',
+    help_opt_headless: 'Output prompt only, no runtime tracking',
+    help_opt_output: 'Save headless prompt to file',
+    help_opt_json: 'JSON output mode',
+    help_agent_options: 'Agent-specific options ({command}):',
+    help_requires: 'Requires:',
+    help_produces: 'Produces:',
+    help_instruction_file: 'Instruction file:',
+    help_unknown_agent: 'Unknown agent: {agent}'
   },
   context_validate: {
     missing_file: 'Context file not found: {path}',
@@ -1090,11 +1107,11 @@ module.exports = {
     plan_not_found: 'Plan file not found: {plan}',
     no_active_session: 'No active live session found for {agent}.',
     session_not_active: 'Live session for {agent} is not active.',
-    json_requires_no_launch: '--json requires --no-launch for live:start because foreground launch is interactive.',
-    tool_binary_not_found: 'Tool binary not found in PATH: {binary}',
-    tool_mismatch: 'Active session uses tool "{existing}" but --tool={requested} was given. Close the session first or use the same tool.',
-    tool_mismatch_auto_closed: 'Previous live session used "{existing}" and was auto-closed. Starting a new session with "{requested}".',
-    micro_task_already_open: 'A live micro-task is already open for {agent}. Emit task_completed before task_started again.',
+    json_requires_no_launch: '--json requires --no-launch for live:start because foreground launch is interactive.',
+    tool_binary_not_found: 'Tool binary not found in PATH: {binary}',
+    tool_mismatch: 'Active session uses tool "{existing}" but --tool={requested} was given. Close the session first or use the same tool.',
+    tool_mismatch_auto_closed: 'Previous live session used "{existing}" and was auto-closed. Starting a new session with "{requested}".',
+    micro_task_already_open: 'A live micro-task is already open for {agent}. Emit task_completed before task_started again.',
     handoff_same_agent: 'live:handoff requires different --agent and --to values.',
     handoff_agent_mismatch: 'No active live session found for {agent}.',
     watch_json_conflict: '--watch cannot be combined with --json.',

package/src/i18n/messages/es.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=es]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=es]',
@@ -383,7 +385,22 @@ module.exports = {
       'Pentester app_target requiere --feature=<slug> (o --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target requiere --scope=<area>.',
-    prompt_title: 'Prompt para el agente "{agent}" en la herramienta "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt para el agente "{agent}" en la herramienta "{tool}" (locale: {locale}):',
+    help_available: 'Agentes disponibles:',
+    help_run_detail: 'Ejecute "aioson agent:help <nombre>" para detalles de un agente específico.',
+    help_usage: 'Uso:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Opciones comunes:',
+    help_opt_tool: 'Herramienta destino (codex|claude|gemini|opencode)',
+    help_opt_language: 'Idioma de interacción (ej: pt-BR, en)',
+    help_opt_headless: 'Solo salida del prompt, sin rastreo de runtime',
+    help_opt_output: 'Guardar prompt headless en archivo',
+    help_opt_json: 'Modo de salida JSON',
+    help_agent_options: 'Opciones específicas del agente ({command}):',
+    help_requires: 'Requiere:',
+    help_produces: 'Produce:',
+    help_instruction_file: 'Archivo de instrucción:',
+    help_unknown_agent: 'Agente desconocido: {agent}'
   },
   context_validate: {
     missing_file: 'Archivo de contexto no encontrado: {path}',

package/src/i18n/messages/fr.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=fr]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=fr]',
@@ -382,7 +384,22 @@ module.exports = {
       'Pentester app_target exige --feature=<slug> (ou --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target exige --scope=<area>.',
-    prompt_title: 'Prompt pour l agent "{agent}" sur l outil "{tool}" (locale : {locale}) :'
+    prompt_title: 'Prompt pour l agent "{agent}" sur l outil "{tool}" (locale : {locale}) :',
+    help_available: 'Agents disponibles :',
+    help_run_detail: 'Exécutez "aioson agent:help <nom>" pour les détails d un agent spécifique.',
+    help_usage: 'Utilisation :',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Options communes :',
+    help_opt_tool: 'Outil cible (codex|claude|gemini|opencode)',
+    help_opt_language: 'Langue d interaction (ex : pt-BR, en)',
+    help_opt_headless: 'Sortie du prompt uniquement, sans suivi runtime',
+    help_opt_output: 'Enregistrer le prompt headless dans un fichier',
+    help_opt_json: 'Mode de sortie JSON',
+    help_agent_options: 'Options spécifiques de l agent ({command}) :',
+    help_requires: 'Requiert :',
+    help_produces: 'Produit :',
+    help_instruction_file: 'Fichier d instruction :',
+    help_unknown_agent: 'Agent inconnu : {agent}'
   },
   context_validate: {
     missing_file: 'Fichier de contexte introuvable : {path}',

package/src/i18n/messages/pt-BR.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
@@ -217,7 +219,7 @@ module.exports = {
     help_runtime_emit:
       'aioson runtime:emit [path] --agent=<nome> [--type=<evento>] [--summary=<texto>] [--title=<texto>] [--refs=<arquivo[,arquivo2]>] [--plan-step=<id>] [--meta=<json>] [--json] [--locale=pt-BR]',
     help_live_start:
-      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<nome> [--tool-bin=<binario>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<texto>] [--goal=<texto>] [--plan=<arquivo>] [--session=<chave>] [--message=<texto>] [--attach] [--no-launch] [--tmux] [--json] [--locale=pt-BR]',
+      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<nome> [--tool-bin=<binario>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<texto>] [--goal=<texto>] [--plan=<arquivo>] [--session=<chave>] [--message=<texto>] [--attach] [--no-launch] [--tmux] [--json] [--locale=pt-BR]',
     help_live_status:
       'aioson live:status [path] [--agent=<nome>] [--limit=8] [--watch=2] [--format=compact|tmux-bar] [--json] [--locale=pt-BR]',
     help_live_handoff:
@@ -477,7 +479,22 @@ module.exports = {
       'Pentester app_target exige --feature=<slug> (ou --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target exige --scope=<area>.',
-    prompt_title: 'Prompt para o agente "{agent}" na ferramenta "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt para o agente "{agent}" na ferramenta "{tool}" (locale: {locale}):',
+    help_available: 'Agentes disponíveis:',
+    help_run_detail: 'Execute "aioson agent:help <nome>" para detalhes de um agente específico.',
+    help_usage: 'Uso:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Opções comuns:',
+    help_opt_tool: 'Ferramenta alvo (codex|claude|gemini|opencode)',
+    help_opt_language: 'Idioma de interação (ex: pt-BR, en)',
+    help_opt_headless: 'Saída apenas do prompt, sem rastreamento de runtime',
+    help_opt_output: 'Salvar prompt headless em arquivo',
+    help_opt_json: 'Modo de saída JSON',
+    help_agent_options: 'Opções específicas do agente ({command}):',
+    help_requires: 'Requer:',
+    help_produces: 'Produz:',
+    help_instruction_file: 'Arquivo de instrução:',
+    help_unknown_agent: 'Agente desconhecido: {agent}'
   },
   context_validate: {
     missing_file: 'Arquivo de contexto nao encontrado: {path}',
@@ -1116,11 +1133,11 @@ module.exports = {
     plan_not_found: 'Arquivo de plano nao encontrado: {plan}',
     no_active_session: 'Nenhuma sessao live ativa encontrada para {agent}.',
     session_not_active: 'A sessao live de {agent} nao esta ativa.',
-    json_requires_no_launch: '--json requer --no-launch para live:start porque o lancamento em primeiro plano e interativo.',
-    tool_binary_not_found: 'Binario da ferramenta nao encontrado no PATH: {binary}',
-    tool_mismatch: 'A sessao ativa usa a ferramenta "{existing}" mas --tool={requested} foi informado. Encerre a sessao primeiro ou use a mesma ferramenta.',
-    tool_mismatch_auto_closed: 'A sessao live anterior usava "{existing}" e foi fechada automaticamente. Iniciando nova sessao com "{requested}".',
-    micro_task_already_open: 'Uma micro-tarefa live ja esta aberta para {agent}. Emita task_completed antes de task_started novamente.',
+    json_requires_no_launch: '--json requer --no-launch para live:start porque o lancamento em primeiro plano e interativo.',
+    tool_binary_not_found: 'Binario da ferramenta nao encontrado no PATH: {binary}',
+    tool_mismatch: 'A sessao ativa usa a ferramenta "{existing}" mas --tool={requested} foi informado. Encerre a sessao primeiro ou use a mesma ferramenta.',
+    tool_mismatch_auto_closed: 'A sessao live anterior usava "{existing}" e foi fechada automaticamente. Iniciando nova sessao com "{requested}".',
+    micro_task_already_open: 'Uma micro-tarefa live ja esta aberta para {agent}. Emita task_completed antes de task_started novamente.',
     handoff_same_agent: 'live:handoff requer valores diferentes para --agent e --to.',
     handoff_agent_mismatch: 'Nenhuma sessao live ativa encontrada para {agent}.',
     watch_json_conflict: '--watch nao pode ser combinado com --json.',

package/template/.claude/commands/aioson/agent/analyst.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Domain discovery and entity mapping (SMALL/MEDIUM)"
----
-
-Read `.aioson/agents/analyst.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Domain discovery and entity mapping (SMALL/MEDIUM)"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@analyst — Domain discovery and entity mapping (SMALL/MEDIUM)
+Usage: /aioson:agent:analyst [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: .aioson/context/discovery.md
+Instruction file: .aioson/agents/analyst.md
+CLI help: aioson agent:help analyst
+
+Otherwise: Read `.aioson/agents/analyst.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/architect.md

@@ -1,5 +1,17 @@
----
-description: "AIOSON — Project structure and technical decisions (SMALL/MEDIUM)"
----
-
-Read `.aioson/agents/architect.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Project structure and technical decisions (SMALL/MEDIUM)"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@architect — Project structure and technical decisions (SMALL/MEDIUM)
+Usage: /aioson:agent:architect [task description]
+Requires:
+  .aioson/context/project.context.md
+  .aioson/context/discovery.md
+Produces: .aioson/context/architecture.md
+Instruction file: .aioson/agents/architect.md
+CLI help: aioson agent:help architect
+
+Otherwise: Read `.aioson/agents/architect.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/briefing.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Pre-production briefings and planning"
----
-
-Read `.aioson/agents/briefing.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Pre-production briefings and planning"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@briefing — Pre-production briefings and planning
+Usage: /aioson:agent:briefing [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: .aioson/briefings/{slug}/
+Instruction file: .aioson/agents/briefing.md
+CLI help: aioson agent:help briefing
+
+Otherwise: Read `.aioson/agents/briefing.md` and follow all instructions. $ARGUMENTS