@jaimevalasek/aioson 1.3.0 → 1.4.0

package/src/context-writer.js

@@ -63,6 +63,7 @@ function renderProjectContext(data) {
   const language = data.conversationLanguage || 'en';
   const codeCommentLanguage = data.codeCommentLanguage || language;
   const generatedAt = data.generatedAt || new Date().toISOString();
+  const designSkill = data.designSkill || '';
   const web3Enabled = Boolean(data.web3Enabled);
   const web3Networks = data.web3Networks || '';
   const contractFramework = data.contractFramework || '';
@@ -79,6 +80,7 @@ framework: "${data.framework}"
 framework_installed: ${data.frameworkInstalled ? 'true' : 'false'}
 classification: "${data.classification}"
 conversation_language: "${language}"
+design_skill: "${designSkill}"
 web3_enabled: ${web3Enabled ? 'true' : 'false'}
 web3_networks: "${web3Networks}"
 contract_framework: "${contractFramework}"

package/src/delivery-runner.js

@@ -0,0 +1,319 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const MAX_RETRIES = 3;
+const RETRY_DELAYS = [1000, 3000, 8000]; // ms — exponential-ish backoff
+
+function resolveEnvPlaceholders(value) {
+  return String(value || '').replace(/\{\{ENV:(\w+)\}\}/g, (_, varName) => {
+    return process.env[varName] || '';
+  });
+}
+
+function nowIso() {
+  return new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
+}
+
+function logDelivery(db, entry) {
+  db.prepare(`
+    INSERT INTO delivery_log (squad_slug, content_key, webhook_slug, trigger_type, url, status_code, response_body, error_message, attempt, created_at)
+    VALUES (@squad_slug, @content_key, @webhook_slug, @trigger_type, @url, @status_code, @response_body, @error_message, @attempt, @created_at)
+  `).run({
+    squad_slug: entry.squadSlug,
+    content_key: entry.contentKey || null,
+    webhook_slug: entry.webhookSlug || null,
+    trigger_type: entry.triggerType,
+    url: entry.url,
+    status_code: entry.statusCode ?? null,
+    response_body: entry.responseBody ? String(entry.responseBody).slice(0, 2000) : null,
+    error_message: entry.errorMessage || null,
+    attempt: entry.attempt || 1,
+    created_at: nowIso()
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function executeWebhookHttp(url, headers, payload) {
+  const body = JSON.stringify(payload);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15000);
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body,
+      signal: controller.signal
+    });
+
+    const responseBody = await response.text().catch(() => '');
+    return {
+      statusCode: response.status,
+      responseBody,
+      ok: response.status >= 200 && response.status < 300
+    };
+  } catch (err) {
+    return {
+      statusCode: null,
+      responseBody: null,
+      ok: false,
+      errorMessage: err.name === 'AbortError' ? 'Request timeout (15s)' : err.message
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function executeWorkerScript(workerPath, payload) {
+  return new Promise((resolve) => {
+    const child = spawn('python3', [workerPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 30000,
+      env: { ...process.env }
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (data) => { stdout += data; });
+    child.stderr.on('data', (data) => { stderr += data; });
+
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+
+    child.on('close', (code) => {
+      resolve({
+        statusCode: code === 0 ? 200 : 500,
+        responseBody: stdout.slice(0, 2000),
+        ok: code === 0,
+        errorMessage: code !== 0 ? (stderr.slice(0, 500) || `Worker exited with code ${code}`) : null
+      });
+    });
+
+    child.on('error', (err) => {
+      resolve({
+        statusCode: null,
+        responseBody: null,
+        ok: false,
+        errorMessage: err.message
+      });
+    });
+  });
+}
+
+function isRetryable(result) {
+  if (result.errorMessage) return true; // network error, timeout
+  if (!result.statusCode) return true;
+  // Retry on 5xx and 429 (rate limit)
+  return result.statusCode >= 500 || result.statusCode === 429;
+}
+
+async function deliverWebhook(db, { squadSlug, contentKey, webhook, triggerType, payload, projectDir }) {
+  const resolvedUrl = resolveEnvPlaceholders(webhook.url);
+  if (!resolvedUrl) {
+    logDelivery(db, {
+      squadSlug,
+      contentKey,
+      webhookSlug: webhook.slug,
+      triggerType,
+      url: webhook.url || '(empty)',
+      errorMessage: 'URL resolved to empty — check ENV variable',
+      attempt: 1
+    });
+    return { ok: false, error: 'URL resolved to empty' };
+  }
+
+  const resolvedHeaders = {};
+  if (webhook.headers && typeof webhook.headers === 'object') {
+    for (const [key, value] of Object.entries(webhook.headers)) {
+      resolvedHeaders[key] = resolveEnvPlaceholders(value);
+    }
+  }
+
+  // Decide execution path: worker script or direct HTTP
+  const hasWorker = webhook.worker && typeof webhook.worker === 'string';
+  let workerAbsPath = null;
+  if (hasWorker) {
+    workerAbsPath = path.resolve(projectDir, webhook.worker);
+    try {
+      await fs.access(workerAbsPath);
+    } catch {
+      workerAbsPath = null; // Worker not found, fall back to HTTP
+    }
+  }
+
+  let lastResult = null;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 1) {
+      await sleep(RETRY_DELAYS[attempt - 2] || 8000);
+    }
+
+    if (workerAbsPath) {
+      lastResult = await executeWorkerScript(workerAbsPath, payload);
+    } else {
+      lastResult = await executeWebhookHttp(resolvedUrl, resolvedHeaders, payload);
+    }
+
+    logDelivery(db, {
+      squadSlug,
+      contentKey,
+      webhookSlug: webhook.slug,
+      triggerType,
+      url: resolvedUrl,
+      statusCode: lastResult.statusCode,
+      responseBody: lastResult.responseBody,
+      errorMessage: lastResult.errorMessage || null,
+      attempt
+    });
+
+    if (lastResult.ok) {
+      return { ok: true, statusCode: lastResult.statusCode, attempts: attempt };
+    }
+
+    if (!isRetryable(lastResult)) {
+      return { ok: false, statusCode: lastResult.statusCode, error: lastResult.errorMessage, attempts: attempt };
+    }
+  }
+
+  return {
+    ok: false,
+    statusCode: lastResult?.statusCode ?? null,
+    error: lastResult?.errorMessage || `Failed after ${MAX_RETRIES} attempts`,
+    attempts: MAX_RETRIES
+  };
+}
+
+async function readSquadManifestJson(projectDir, squadSlug) {
+  const paths = [
+    path.join(projectDir, '.aioson', 'squads', squadSlug, 'squad.manifest.json'),
+    path.join(projectDir, 'agents', squadSlug, 'squad.manifest.json')
+  ];
+
+  for (const manifestPath of paths) {
+    try {
+      const raw = await fs.readFile(manifestPath, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function getOutputStrategy(manifest) {
+  if (manifest.outputStrategy && typeof manifest.outputStrategy === 'object') {
+    return manifest.outputStrategy;
+  }
+  return null;
+}
+
+function getWebhooksForTrigger(outputStrategy, triggerType) {
+  if (!outputStrategy || !outputStrategy.delivery) return [];
+  const webhooks = Array.isArray(outputStrategy.delivery.webhooks) ? outputStrategy.delivery.webhooks : [];
+  return webhooks.filter((wh) => wh.trigger === triggerType || wh.trigger === 'on-create');
+}
+
+/**
+ * Main entry point — called after content item is upserted.
+ * Checks if auto-publish is enabled and fires matching webhooks.
+ */
+async function runAutoDelivery(db, { projectDir, squadSlug, contentKey, contentPayload }) {
+  const manifest = await readSquadManifestJson(projectDir, squadSlug);
+  if (!manifest) return { delivered: false, reason: 'no_manifest' };
+
+  const strategy = getOutputStrategy(manifest);
+  if (!strategy) return { delivered: false, reason: 'no_output_strategy' };
+
+  const delivery = strategy.delivery && typeof strategy.delivery === 'object' ? strategy.delivery : {};
+  if (!delivery.autoPublish) return { delivered: false, reason: 'auto_publish_disabled' };
+
+  const webhooks = getWebhooksForTrigger(strategy, 'on-publish');
+  if (webhooks.length === 0) return { delivered: false, reason: 'no_matching_webhooks' };
+
+  const payload = {
+    squadSlug,
+    contentKey,
+    timestamp: new Date().toISOString(),
+    content: contentPayload || null
+  };
+
+  const results = [];
+  for (const webhook of webhooks) {
+    const result = await deliverWebhook(db, {
+      squadSlug,
+      contentKey,
+      webhook,
+      triggerType: 'auto',
+      payload,
+      projectDir
+    });
+    results.push({ webhookSlug: webhook.slug, ...result });
+  }
+
+  return {
+    delivered: true,
+    results,
+    allOk: results.every((r) => r.ok)
+  };
+}
+
+/**
+ * Manual delivery — triggered by CLI command or dashboard action.
+ * Fires all webhooks matching the given trigger type for a content item.
+ */
+async function runManualDelivery(db, { projectDir, squadSlug, contentKey, triggerType = 'manual', contentPayload }) {
+  const manifest = await readSquadManifestJson(projectDir, squadSlug);
+  if (!manifest) return { delivered: false, reason: 'no_manifest' };
+
+  const strategy = getOutputStrategy(manifest);
+  if (!strategy) return { delivered: false, reason: 'no_output_strategy' };
+
+  const delivery = strategy.delivery && typeof strategy.delivery === 'object' ? strategy.delivery : {};
+  const webhooks = Array.isArray(delivery.webhooks) ? delivery.webhooks : [];
+
+  const matching = triggerType === 'manual'
+    ? webhooks
+    : webhooks.filter((wh) => wh.trigger === triggerType);
+
+  if (matching.length === 0) return { delivered: false, reason: 'no_matching_webhooks' };
+
+  const payload = {
+    squadSlug,
+    contentKey,
+    timestamp: new Date().toISOString(),
+    content: contentPayload || null
+  };
+
+  const results = [];
+  for (const webhook of matching) {
+    const result = await deliverWebhook(db, {
+      squadSlug,
+      contentKey,
+      webhook,
+      triggerType,
+      payload,
+      projectDir
+    });
+    results.push({ webhookSlug: webhook.slug, ...result });
+  }
+
+  return {
+    delivered: true,
+    results,
+    allOk: results.every((r) => r.ok)
+  };
+}
+
+module.exports = {
+  runAutoDelivery,
+  runManualDelivery,
+  deliverWebhook,
+  resolveEnvPlaceholders
+};

package/src/genome-files.js

@@ -12,7 +12,7 @@ const { assertValidGenome, assertValidGenomeMeta } = require('./genome-schema');
 const { ensureDir, exists } = require('./utils');
 
 function getGenomeDir(projectRoot) {
-  return path.join(projectRoot, '.aioson', 'genomas');
+  return path.join(projectRoot, '.aioson', 'genomes');
 }
 
 function getGenomeMarkdownPath(projectRoot, slug) {

package/src/genome-format.js

@@ -271,7 +271,7 @@ function extractTitle(markdown) {
     const match = line.match(/^#\s+(.+?)\s*$/);
     if (!match) continue;
     return match[1]
-      .replace(/^(Genome|Genoma)\s*:\s*/i, '')
+      .replace(/^(Genome|Genome)\s*:\s*/i, '')
       .trim();
   }
   return '';

package/src/i18n/messages/en.js

@@ -18,6 +18,8 @@ module.exports = {
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=en|pt-BR|es|fr] [--locale=en]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
     help_setup_context:
       'aioson setup:context [path] [--defaults] [--project-type=web_app|api|site|script|dapp] [--framework=<name>] [--backend=<name>] [--frontend=<name>] [--database=<name>] [--auth=<name>] [--uiux=<name>] [--language=en] [--web3-enabled=true|false] [--locale=en]',
     help_locale_apply: 'aioson locale:apply [path] [--lang=en|pt-BR|es|fr] [--dry-run] [--locale=en]',
@@ -30,7 +32,9 @@ module.exports = {
     help_workflow_plan:
       'aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json] [--locale=en]',
     help_workflow_next:
-      'aioson workflow:next [path] [--complete[=<agent>]] [--agent=<agent>] [--skip=<agent>] [--tool=codex|claude|gemini|opencode] [--json] [--locale=en]',
+      'aioson workflow:next [path] [--complete[=<agent>]] [--agent=<agent>] [--skip=<agent>] [--status] [--tool=codex|claude|gemini|opencode] [--json] [--locale=en]',
+    help_workflow_status:
+      'aioson workflow:status [path] [--json] [--locale=en]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=en]',
     help_parallel_doctor:
@@ -54,7 +58,7 @@ module.exports = {
     help_qa_report:
       'aioson qa:report [path] [--html] [--json] [--locale=en]',
     help_scan_project:
-      'aioson scan:project [path] --folder=<path[,path2]> [--summary-mode=titles|summaries|raw] [--with-llm] [--provider=<name>] [--llm-model=<name>] [--dry-run] [--json] [--locale=en]',
+      'aioson scan:project [path] --folder=<path[,path2]> [--summary-mode=titles|summaries|raw] [--context-mode=merge|rewrite] [--with-llm] [--provider=<name>] [--llm-model=<name>] [--dry-run] [--json] [--locale=en]',
     help_config:
       'aioson config <set KEY=value|show|get KEY> [--json] [--locale=en]',
     help_genome_doctor:
@@ -73,6 +77,18 @@ module.exports = {
       'aioson squad:export [path] --squad=<slug> [--locale=en]',
     help_squad_pipeline:
       'aioson squad:pipeline [path] [--sub=list|show|status] [--pipeline=<slug>] [--locale=en]',
+    help_squad_agent_create:
+      'aioson squad:agent-create [path] --name=<name> [--scope=my-agents|squad] [--squad=<slug>] [--type=agent|assistant|clone|worker] [--tier=0|1|2|3] [--disc=<profile>] [--mission=<text>] [--domain=<text>] [--specialist=<name>] [--with-infra] [--locale=en]',
+    help_squad_investigate:
+      'aioson squad:investigate [path] [--sub=list|show|score|link|register] [--investigation=<slug>] [--squad=<slug>] [--locale=en]',
+    help_plan:
+      'aioson plan [path] [--sub=show|status|checkpoint|stale|register] [--feature=<slug>] [--phase=<N>] [--locale=en]',
+    help_squad_plan:
+      'aioson squad:plan [path] [--sub=show|status|checkpoint|stale|register] [--squad=<slug>] [--round=<N>] [--locale=en]',
+    help_squad_learning:
+      'aioson squad:learning [path] [--sub=list|stats|archive|promote|export] [--squad=<slug>] [--status=<status>] [--locale=en]',
+    help_learning:
+      'aioson learning [path] [--sub=list|stats|promote] [--status=<status>] [--id=<learning-id>] [--locale=en]',
     help_runtime_init:
       'aioson runtime:init [path] [--json] [--locale=en]',
     help_runtime_ingest:
@@ -95,6 +111,36 @@ module.exports = {
       'aioson runtime:status [path] [--json] [--locale=en]',
     help_runtime_log:
       'aioson runtime:log [path] --agent=<name> --message=<text> [--type=<event>] [--finish] [--status=completed|failed] [--summary=<text>] [--title=<task-title>] [--json] [--locale=en]',
+    help_runtime_session_start:
+      'aioson runtime:session:start [path] --agent=<name> [--title=<text>] [--message=<text>] [--session=<key>] [--json] [--locale=en]',
+    help_runtime_session_log:
+      'aioson runtime:session:log [path] --agent=<name> --message=<text> [--type=<event>] [--title=<text>] [--json] [--locale=en]',
+    help_runtime_session_finish:
+      'aioson runtime:session:finish [path] --agent=<name> [--message=<text>] [--summary=<text>] [--status=completed|failed] [--json] [--locale=en]',
+    help_runtime_session_status:
+      'aioson runtime:session:status [path] --agent=<name> [--limit=8] [--watch=2] [--json] [--locale=en]',
+    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>] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--json] [--locale=en]',
+    help_live_status:
+      'aioson live:status [path] [--agent=<name>] [--limit=8] [--watch=2] [--json] [--locale=en]',
+    help_live_handoff:
+      'aioson live:handoff [path] --agent=<name> --to=<name> [--reason=<text>] [--summary=<text>] [--message=<text>] [--json] [--locale=en]',
+    help_live_close:
+      'aioson live:close [path] [--agent=<name>] [--summary=<text>] [--message=<text>] [--status=completed|failed] [--json] [--locale=en]',
+    help_live_list:
+      'aioson live:list [path] [--json] [--locale=en]',
+    help_runtime_backup:
+      'aioson runtime:backup [path] [--tables=tasks,runs,...] [--force] [--dry-run] [--json] [--locale=en]',
+    help_runtime_restore:
+      'aioson runtime:restore [path] [--tables=tasks,runs,...] [--dry-run] [--json] [--locale=en]',
+    help_skill_install:
+      'aioson skill:install [path] --slug=<name> [--from=npm|cloud|./path] [--force] [--json] [--locale=en]',
+    help_skill_list:
+      'aioson skill:list [path] [--json] [--locale=en]',
+    help_skill_remove:
+      'aioson skill:remove [path] --slug=<name> [--json] [--locale=en]',
     help_cloud_import_squad:
       'aioson cloud:import:squad [path] --url=<snapshot-url> [--force] [--snapshots-only] [--dry-run] [--json] [--locale=en]',
     help_cloud_import_genome:
@@ -147,7 +193,7 @@ module.exports = {
     step_agent_prompt: '3. Generate setup prompt for your tool: aioson agent:prompt setup --tool={tool}',
     existing_project_detected: '⚠ Existing project detected ({count} files). Run the scanner before starting:',
     existing_project_scan_hint:
-      '  aioson scan:project --folder=src   (builds scan-index.md locally; add --with-llm to generate discovery.md)'
+      '  aioson scan:project . --folder=src --with-llm --provider=<provider>   (generates discovery.md + skeleton-system.md; omit --with-llm for local maps only)'
   },
   update: {
     not_installed: 'No AIOSON installation found in {targetDir}.',
@@ -243,7 +289,7 @@ module.exports = {
     active_path: 'Active path',
     depends: 'Depends on',
     output: 'Output',
-    agent_line: '- Agent: {command} ({id})',
+    agent_line: '- Agent: {label} - {command} ({id})',
     path_line: '  Path: {path}',
     active_path_line: '  Active path: {path}',
     depends_line: '  Depends on: {value}',
@@ -269,6 +315,13 @@ module.exports = {
     issue_line: '- {issue}',
     valid: 'Context file is valid.'
   },
+  context_pack: {
+    generated: 'Context pack written to: {path}',
+    no_matches: 'No relevant context files were selected yet. Run setup/context/scan before packing.',
+    selected_title: 'Files included in the pack:',
+    selected_line: '  {index}. {path} — {reason}',
+    hint_use: 'Use {path} as the minimum starting context in your AI session.'
+  },
   setup_context: {
     detected: 'Detected framework: {framework} (installed={installed})',
     q_project_name: 'Project name',
@@ -712,7 +765,38 @@ module.exports = {
     status_active_task_line: '- {task} | squad: {squad} | status: {status} | work: {title}',
     status_no_active: 'No active agent runs.',
     status_active_title: 'Active runs:',
-    status_active_line: '- {agent} | squad: {squad} | status: {status} | work: {title}'
+    status_active_line: '- {agent} | squad: {squad} | status: {status} | work: {title}',
+    status_live_sessions_title: 'Active live sessions:',
+    status_live_session_line: '- {task} | agent: {agent} | status: {status} | plan: {plan} | micro: {micro} | handoffs: {handoffs} | work: {title}',
+    status_micro_tasks_title: 'Active micro-tasks:',
+    status_micro_task_line: '- {task} | parent: {parent} | status: {status} | work: {title}',
+    status_handoffs_title: 'Recent handoffs:',
+    status_handoff_line: '- {created} | {from} -> {to} | session: {session} | {message}'
+  },
+  live: {
+    unsupported_tool: 'Unsupported live tool: {tool}. Supported tools: {supported}',
+    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.',
+    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.',
+    no_session_found: 'No live session found.',
+    no_session_for_agent: 'No live session found for {agent}.',
+    session_already_closed: 'Live session {session} is already closed.',
+    session_already_active: 'Live session already active: {agent} | session: {session} | run: {runKey} ({dbPath})',
+    session_started: 'Live session started: {agent} | tool: {tool} | session: {session} ({dbPath})',
+    event_recorded: 'Live event recorded: {agent} | {eventType} | {session} ({dbPath})',
+    handoff_recorded: 'Live handoff recorded: {from} -> {to} | {session} ({dbPath})',
+    session_closed: 'Live session closed: {agent} | {session} ({dbPath})',
+    process_dead_warning: 'Process is dead while the live session is still open. Close it manually with `aioson live:close . --status=failed`.',
+    list_title: 'Live sessions ({count}):',
+    list_empty: 'No live sessions found.',
+    list_line: '- {session} | {agent} | {tool} | {phase} | {updatedAt}'
   },
   squad_status: {
     no_squad: 'No squads found.',
@@ -729,6 +813,17 @@ module.exports = {
     logs: '    Logs        : {count} ({path})',
     genomes: '    Genomes     : {count} squad-level / {agent_count} agent bindings'
   },
+  squad_agent_create: {
+    no_name: 'Usage: aioson squad:agent-create [path] --name=<agent-name> [--type=agent|assistant|clone|worker] [--scope=my-agents|squad] [--squad=<slug>]',
+    invalid_scope: 'Invalid scope: "{scope}". Use "my-agents" or "squad".',
+    invalid_type: 'Invalid type: "{type}". Use: agent, assistant, clone, worker.',
+    invalid_tier: 'Invalid tier: "{tier}". Use: 0 (foundation), 1 (master), 2 (systematizer), 3 (specialist).',
+    invalid_disc: 'Invalid DISC profile: "{disc}".',
+    no_squads: 'No squads found. Create a squad first with @squad or provide --squad=<slug>.',
+    squad_required: '--squad=<slug> required when scope is "squad".',
+    squad_not_found: 'Squad "{squad}" not found.',
+    already_exists: 'Agent already exists: {path}'
+  },
   squad_doctor: {
     prefix_ok: 'OK',
     prefix_warn: 'WARN',
@@ -752,6 +847,19 @@ module.exports = {
     scanning: 'aioson scan:project — scanning {dir}',
     folder_required:
       'Pass --folder=<path[,path2]> to generate full scans for specific folders. Example: --folder=src or --folder=app.',
+    folder_required_examples_title: '\x1b[33mQuick start:\x1b[0m',
+    folder_required_example_local:
+      '  Local maps only : aioson scan:project . --folder=src',
+    folder_required_example_multi:
+      '  Multiple folders: aioson scan:project . --folder=src,app',
+    folder_required_example_llm:
+      '  API automation  : aioson scan:project . --folder=src --with-llm --provider=openai',
+    folder_required_example_cli:
+      '  No API in aioson: aioson scan:project . --folder=src  -> then run @analyst in Codex/Claude/Gemini',
+    folder_required_example_prompt:
+      '  Ready prompt    : aioson agent:prompt analyst --tool=codex',
+    folder_required_example_next:
+      '  Workflow after full scan: @analyst -> @architect -> @dev',
     folder_not_found: 'Folder "{folder}" was not found in this project. Top-level directories detected: {available}',
     config_missing: '{file} not found. To use LLM mode, copy aioson-models.json and fill in your API keys.',
     config_invalid: 'Invalid JSON in aioson-models.json: {error}',
@@ -761,6 +869,10 @@ module.exports = {
     context_found: '  Context  : project.context.md found',
     context_missing: '  Context  : project.context.md not found (run aioson setup:context first)',
     spec_found: '  Spec     : spec.md found — development memory included',
+    existing_discovery_found: '  Context  : existing discovery.md found at {path}',
+    existing_skeleton_found: '  Context  : existing skeleton-system.md found at {path}',
+    context_update_mode: '  Mode     : update/merge of existing discovery.md + skeleton-system.md enabled',
+    context_mode: '  Context  : context-mode={mode} (recommended default for brownfield: merge)',
     local_only: '  LLM      : disabled by default — local scan only (use --with-llm to generate discovery.md + skeleton-system.md)',
     walking: '  Scanning project structure...',
     walk_done: '  Files    : {files} entries mapped | Key files: {keys} read',
@@ -768,17 +880,104 @@ module.exports = {
     folders_written: '  Folders  : folder map written to {path}',
     folder_written: '  Folder   : full map for {folder} written to {path}',
     forge_written: '  AIOS     : useful .aioson map written to {path}',
+    memory_index_written: '  Memory   : memory-index.md written to {path}',
+    spec_current_written: '  Memory   : spec-current.md written to {path}',
+    spec_history_written: '  Memory   : spec-history.md written to {path}',
+    module_memory_written: '  Module   : focused memory for {folder} written to {path}',
     dry_run_done: '[dry-run] Would scan {treeCount} entries and {keyCount} key files — no LLM call made.',
     local_done: '  Result   : local scan completed — index, folder map, requested folder scans and .aioson map are ready.',
+    local_missing: '  Missing  : discovery.md + skeleton-system.md were not generated in this local-only scan.',
+    architecture_note: '  Note     : architecture.md is not generated by scan:project; it comes later from @architect.',
+    local_paths_title: '\n\x1b[33m  How to generate discovery now:\x1b[0m',
+    local_path_api: '  \x1b[32mPath A — API automation\x1b[0m',
     calling_llm: '  Calling {provider} ({model})...',
     llm_missing_api_key:
       'The API key for provider "{provider}" is still missing in {file}. Fill providers.{provider}.api_key or choose another provider with --provider=...',
     llm_error: 'LLM call failed: {error}',
+    gitignore_policy_written:
+      '  Gitignore: AIOSON policy updated in {path} to ignore framework-managed files',
+    gitignore_tracked_note:
+      '  Gitignore: if those files were already tracked by Git before, you still need one git rm --cached pass for them to stop appearing in status',
+    invalid_llm_output_discovery_empty:
+      'The LLM returned an empty discovery.md. No existing files were overwritten. Keep the current backup and retry with a stronger model or fewer folders.',
+    invalid_llm_output_skeleton_empty:
+      'The LLM returned an empty skeleton-system.md after the delimiter. No existing files were overwritten. Retry with a stronger model or a smaller scope.',
+    gitignore_backups_written: '  Gitignore: local backup rule ensured in {path}',
+    backups_written: '  Backup   : saved {count} file(s) into {path}',
     discovery_written: 'discovery.md written: {path} ({chars} chars)',
     skeleton_written: 'skeleton-system.md written: {path} ({chars} chars)',
     skeleton_missing: 'Skeleton delimiter not found in LLM response — skeleton-system.md not written.',
+    local_next_steps: '  1. Run: aioson scan:project {target} --folder={folders} --with-llm --provider=<provider>',
+    local_path_cli: '  \x1b[36mPath B — Your AI CLI (no API inside aioson)\x1b[0m',
+    local_cli_step_analyst: '  2. In Codex, Claude Code, or another client, run @analyst — it can use scan-index.md + scan-folders.md + scan-<folder>.md to write discovery.md',
+    local_cli_step_prompt_codex: '  3. If the client does not understand @analyst, generate a ready prompt: aioson agent:prompt analyst --tool=codex',
+    local_cli_step_prompt_claude: '  4. Swap --tool=codex for --tool=claude or --tool=gemini when needed',
+    local_cli_step_model_hint: '  5. If your client supports model selection, prefer a fast/cheap model for this discovery step',
+    local_workflow_title: '\n\x1b[33m  After discovery:\x1b[0m',
+    local_step_architect: '  3. Run @architect — generates architecture.md from the consolidated discovery',
+    local_step_dev: '  4. Run @dev — only start coding after discovery.md + architecture.md are ready',
     next_steps: '\n  Next steps:',
-    step_analyst: '  1. Open your AI coding session and run @analyst — reads discovery.md + skeleton-system.md automatically',
-    step_dev: '  2. Run @dev — reads skeleton-system.md first, then discovery.md + spec.md'
+    step_analyst: '  1. Open your AI coding session and run @analyst — review discovery.md + skeleton-system.md and consolidate the current scope',
+    step_architect: '  2. Run @architect — generates architecture.md from the consolidated discovery',
+    step_dev: '  3. Run @dev — reads skeleton-system.md first, then discovery.md + architecture.md + spec.md'
+  },
+  squad_investigate: {
+    no_runtime: 'Runtime store not found. Run aioson runtime:init first.',
+    no_investigations: 'No investigations found.',
+    not_found: 'Investigation not found: {slug}',
+    no_report: 'Investigation "{slug}" has no report file.',
+    report_missing: 'Report file not found: {path}',
+    show_usage: 'Usage: aioson squad:investigate [path] --sub=show --investigation=<slug>',
+    score_usage: 'Usage: aioson squad:investigate [path] --sub=score --investigation=<slug>',
+    link_usage: 'Usage: aioson squad:investigate [path] --sub=link --investigation=<slug> --squad=<slug>',
+    register_usage: 'Usage: aioson squad:investigate [path] --sub=register --report=<path> [--domain=<name>] [--squad=<slug>]',
+    linked: 'Investigation "{investigation}" linked to squad "{squad}".',
+    registered: 'Investigation registered: {slug} ({path})',
+    unknown_sub: 'Unknown subcommand: {sub}. Use: list, show, score, link, register.'
+  },
+
+  implementation_plan: {
+    not_found: 'Implementation plan not found: {file}',
+    no_runtime: 'Runtime store not found. Run aioson runtime:init first.',
+    no_plans: 'No implementation plans registered.',
+    no_created_date: 'Plan has no created date in frontmatter — cannot check staleness.',
+    is_stale: 'Plan is STALE — source artifacts changed after plan was created.',
+    is_fresh: 'Plan is up to date.',
+    checkpoint_usage: 'Usage: aioson plan [path] --sub=checkpoint --feature=<slug> --phase=<N>',
+    phase_completed: 'Phase {phase} marked as completed.',
+    phase_not_found: 'Phase {phase} not found in plan.',
+    registered: 'Implementation plan registered: {planId} ({phases} phases)'
+  },
+
+  squad_plan: {
+    slug_required: 'Squad slug is required.',
+    not_found: 'Execution plan not found for squad: {slug}',
+    no_runtime: 'Runtime store not found. Run aioson runtime:init first.',
+    no_plan: 'No execution plan registered for squad: {slug}',
+    no_created_date: 'Plan has no created date in frontmatter — cannot check staleness.',
+    is_stale: 'Execution plan is STALE — squad artifacts changed after plan was created.',
+    is_fresh: 'Execution plan is up to date.',
+    checkpoint_usage: 'Usage: aioson squad:plan [path] --sub=checkpoint --squad=<slug> --round=<N>',
+    round_completed: 'Round {round} marked as completed.',
+    round_not_found: 'Round {round} not found in plan.',
+    registered: 'Execution plan registered: {planSlug} ({rounds} rounds)'
+  },
+
+  squad_learning: {
+    slug_required: 'Squad slug is required.',
+    no_runtime: 'Runtime store not found. Run aioson runtime:init first.',
+    no_learnings: 'No learnings found for squad: {slug}',
+    not_found: 'Learning not found: {id}',
+    archived_count: '{count} learning(s) marked as stale for squad: {slug}',
+    promote_usage: 'Usage: aioson squad:learning [path] --sub=promote --squad=<slug> --id=<learning-id> [--to=<rule-path>]',
+    promoted: 'Learning {id} promoted to rule at {path}'
+  },
+
+  learning: {
+    no_runtime: 'Runtime store not found. Run aioson runtime:init first.',
+    no_learnings: 'No project learnings found.',
+    not_found: 'Learning not found: {id}',
+    promote_usage: 'Usage: aioson learning [path] --sub=promote --id=<learning-id> [--to=<rule-path>]',
+    promoted: 'Learning {id} promoted to rule at {path}'
   }
 };