@ariaflowagents/config 0.5.3 → 0.8.0

package/dist/cli.js

@@ -8,12 +8,22 @@
  *   npx ariaflow list agents|flows|tools|skills [--config <path>]
  *   npx ariaflow copy <starter> [--cwd <dir>]
  *   npx ariaflow prompt init --template <id> [--out <path>] [--cwd <dir>] [--force]
+ *   npx ariaflow prompt lint [--path <file-or-dir>] [--config <path>] [--strict] [--json]
  *   npx ariaflow pack init <name> [--starter <id>] [--cwd <dir>] [--force]
+ *   npx ariaflow flow generate --use-case <text> [--out <path>]
+ *   npx ariaflow agent architect --use-case <text> [--mode llm|flow|hybrid]
  */
 import { join, dirname, resolve, relative } from 'path';
 import { fileURLToPath } from 'url';
-import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
 import { loadAriaflowConfigWithResult, printLoadSummary } from './loader.js';
+import { generateFlowTemplate } from './flow-generator.js';
+import { generateFlowTemplateWithLLM } from './llm-flow-generator.js';
+import { emitFlowTypeScriptModule } from './flow-codegen.js';
+import { lintPrompts } from './prompt-lint.js';
+import { runArchitect } from './agent-architect/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AVAILABLE_STARTERS = ['basic', 'sales', 'support', 'bank-hybrid'];
 const AVAILABLE_PACK_STARTERS = ['basic'];
@@ -47,6 +57,10 @@ async function main() {
             await cmdPromptInit(args.slice(2));
             process.exit(0);
         }
+        if (subcommand === 'lint') {
+            await cmdPromptLint(args.slice(2));
+            process.exit(0);
+        }
         printPromptHelp();
         process.exit(0);
     }
@@ -60,6 +74,26 @@ async function main() {
         printPackHelp();
         process.exit(0);
     }
+    // Flow command - generation/templating, doesn't need config
+    if (command === 'flow') {
+        const subcommand = args[1] ?? 'help';
+        if (subcommand === 'generate') {
+            await cmdFlowGenerate(args.slice(2));
+            process.exit(0);
+        }
+        printFlowHelp();
+        process.exit(0);
+    }
+    // Agent command - orchestrated generation, doesn't need config
+    if (command === 'agent') {
+        const subcommand = args[1] ?? 'help';
+        if (subcommand === 'architect') {
+            await cmdAgentArchitect(args.slice(2));
+            process.exit(0);
+        }
+        printAgentHelp();
+        process.exit(0);
+    }
     const options = {
         config: process.env.ARIAFLOW_CONFIG,
     };
@@ -336,6 +370,9 @@ Commands:
   copy <starter>    Copy a starter template to your project
   pack init         Create a pack from a starter template
   prompt init       Create a markdown prompt template file
+  prompt lint       Lint prompt files with Aria quality gates
+  flow generate     Generate a production-style flow JSON scaffold
+  agent architect   Generate blueprint + prompt/flow/code artifacts
   help              Show this help
 
 Options:
@@ -351,6 +388,9 @@ Examples:
   ariaflow copy sales
   ariaflow pack init my-pack --starter basic
   ariaflow prompt init --template support-agent
+  ariaflow prompt lint --strict
+  ariaflow flow generate --use-case "medical appointment scheduling" --out ./.ariaflow/flow/appointments.json
+  ariaflow agent architect --use-case "hospital support triage" --mode hybrid --target both
 `);
 }
 async function cmdPackInit(args) {
@@ -530,22 +570,1205 @@ async function cmdPromptInit(args) {
 }
 function printPromptHelp() {
     console.log(`
-AriaFlow Prompt Init
+AriaFlow Prompt Commands
 
 Usage:
   ariaflow prompt init --template <id> [--out <path>] [--cwd <dir>] [--force]
+  ariaflow prompt lint [--path <file-or-dir>] [--config <path>] [--cwd <dir>] [--strict] [--json]
 
-Creates a markdown prompt template file with the standard sections.
+Subcommands:
+  init                Create a markdown prompt template with standard sections
+  lint                Lint prompts against Aria project quality gates
 
 Options:
   --template <id>  Template id and filename (required)
   --out <path>     Output file path (default: ./.ariaflow/prompts/<id>.md)
   --cwd <dir>      Base directory (default: current directory)
   --force          Overwrite if file exists
+  --path <target>  Lint specific file or directory (default: ./.ariaflow/prompts)
+  --config <path>  Config path for agent-type-aware linting (default: auto-detect)
+  --strict         Treat warnings as failures (non-zero exit)
+  --json           Output machine-readable JSON report
 
 Examples:
   ariaflow prompt init --template support-agent
   ariaflow prompt init --template triage-agent --out .ariaflow/prompts/triage.md
+  ariaflow prompt lint
+  ariaflow prompt lint --path .ariaflow/prompts/triage.md --strict
+`);
+}
+function issueSort(a, b) {
+    if (a.file !== b.file)
+        return a.file.localeCompare(b.file);
+    if (a.severity !== b.severity)
+        return a.severity === 'error' ? -1 : 1;
+    return a.ruleId.localeCompare(b.ruleId);
+}
+async function cmdPromptLint(args) {
+    let cwd = process.cwd();
+    let pathArg;
+    let configPath;
+    let strict = false;
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--cwd' && i + 1 < args.length) {
+            cwd = resolve(args[i + 1]);
+            i++;
+            continue;
+        }
+        if (arg === '--path' && i + 1 < args.length) {
+            pathArg = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--config' && i + 1 < args.length) {
+            configPath = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--strict') {
+            strict = true;
+            continue;
+        }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+    }
+    const result = lintPrompts({
+        cwd,
+        path: pathArg,
+        configPath,
+    });
+    const sortedIssues = [...result.issues].sort(issueSort);
+    const errors = sortedIssues.filter(issue => issue.severity === 'error');
+    const warnings = sortedIssues.filter(issue => issue.severity === 'warn');
+    const shouldFail = errors.length > 0 || (strict && warnings.length > 0);
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            filesScanned: result.filesScanned,
+            issueCount: sortedIssues.length,
+            errors: errors.length,
+            warnings: warnings.length,
+            strict,
+            passed: !shouldFail,
+            issues: sortedIssues,
+        }, null, 2) + '\n');
+        process.exit(shouldFail ? 1 : 0);
+    }
+    console.log('\nAriaFlow Prompt Lint\n');
+    console.log(`Scanned files: ${result.filesScanned.length}`);
+    console.log(`Errors: ${errors.length}`);
+    console.log(`Warnings: ${warnings.length}`);
+    if (strict) {
+        console.log('Mode: strict (warnings fail)');
+    }
+    if (sortedIssues.length === 0) {
+        console.log('\n✅ No issues found.\n');
+        process.exit(0);
+    }
+    console.log('\nIssues:\n');
+    for (const issue of sortedIssues) {
+        const icon = issue.severity === 'error' ? '❌' : '⚠️';
+        const relFile = issue.file.startsWith(cwd) ? `.${issue.file.slice(cwd.length)}` : issue.file;
+        console.log(`${icon} [${issue.severity}] ${issue.ruleId}`);
+        console.log(`   ${issue.message}`);
+        console.log(`   File: ${relFile}\n`);
+    }
+    if (shouldFail) {
+        console.log('❌ Prompt lint failed.\n');
+        process.exit(1);
+    }
+    console.log('✅ Prompt lint passed with warnings.\n');
+}
+function toSlug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64) || 'generated-agent';
+}
+function toTsConstCase(value) {
+    const clean = value.replace(/[^a-zA-Z0-9]+/g, ' ').trim();
+    const words = clean.split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return 'generatedAgent';
+    const [head, ...tail] = words;
+    return `${head.toLowerCase()}${tail.map(word => word[0].toUpperCase() + word.slice(1).toLowerCase()).join('')}`;
+}
+function parseCsv(value) {
+    return value
+        .split(',')
+        .map(item => item.trim())
+        .filter(Boolean);
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values.map(value => value.trim()).filter(Boolean)));
+}
+function ensureWritableFile(target, content, force) {
+    if (existsSync(target) && !force) {
+        throw new Error(`File already exists: ${target}. Use --force to overwrite.`);
+    }
+    const parentDir = dirname(target);
+    if (!existsSync(parentDir)) {
+        mkdirSync(parentDir, { recursive: true });
+    }
+    writeFileSync(target, content, 'utf8');
+}
+function inferDomainSafetyAddendum(useCase) {
+    const lower = useCase.toLowerCase();
+    if (/(medical|health|hospital|clinic|patient|appointment)/.test(lower)) {
+        return 'Treat health and personal data as sensitive. Collect only minimum required details, avoid exposing full identifiers, and do not provide medical diagnosis. If symptoms indicate emergency risk, instruct immediate emergency care and escalate.';
+    }
+    if (/(bank|billing|payment|finance|loan|refund|invoice)/.test(lower)) {
+        return 'Treat financial data as sensitive. Never request full card or account secrets in plain text. Confirm all money movement actions explicitly before execution.';
+    }
+    if (/(legal|law|contract|compliance)/.test(lower)) {
+        return 'Do not present legal conclusions as professional legal advice. State uncertainty clearly and recommend qualified human review for high-impact legal decisions.';
+    }
+    return '';
+}
+function normalizeGeneratedText(text) {
+    if (!text || text.trim().length === 0) {
+        return text;
+    }
+    const compactSpaces = text
+        .replace(/\r\n/g, '\n')
+        .replace(/\.\./g, '.')
+        .replace(/[ \t]{2,}/g, ' ')
+        .replace(/We are getting (inbound|outbound) calls for/gi, 'You are handling $1 calls for')
+        .replace(/:\s+\./g, ':');
+    const withSectionBreaks = compactSpaces
+        .replace(/([.!?])\s+(##?\s+)/g, '$1\n\n$2')
+        .replace(/\n{3,}/g, '\n\n');
+    return withSectionBreaks
+        .split('\n')
+        .map(line => line.trimEnd())
+        .join('\n')
+        .trim();
+}
+function normalizeFlowDraft(flow) {
+    return {
+        ...flow,
+        defaultRolePrompt: flow.defaultRolePrompt ? normalizeGeneratedText(flow.defaultRolePrompt) : flow.defaultRolePrompt,
+        nodes: flow.nodes.map(node => ({
+            ...node,
+            prompt: typeof node.prompt === 'string' ? normalizeGeneratedText(node.prompt) : node.prompt,
+        })),
+    };
+}
+function addTransitionGuidance(flow) {
+    if (!flow.transitions || flow.transitions.length === 0) {
+        return flow;
+    }
+    const transitionsByFrom = new Map();
+    for (const transition of flow.transitions) {
+        if (!transition.from || !transition.on) {
+            continue;
+        }
+        const list = transitionsByFrom.get(transition.from) ?? [];
+        list.push(transition.on);
+        transitionsByFrom.set(transition.from, list);
+    }
+    return {
+        ...flow,
+        nodes: flow.nodes.map(node => {
+            const options = transitionsByFrom.get(node.id) ?? [];
+            if (options.length === 0 || typeof node.prompt !== 'string') {
+                return node;
+            }
+            const uniqueOptions = uniqueStrings(options);
+            const guidance = [
+                '',
+                '## Transition Emission',
+                `When this node is complete, emit exactly one transition event from: ${uniqueOptions.join(', ')}.`,
+                'Do not emit transition events before required data is confirmed.',
+            ].join('\n');
+            return {
+                ...node,
+                prompt: `${node.prompt}${guidance}`,
+            };
+        }),
+    };
+}
+function inferSuggestedToolSlots(useCase) {
+    const lower = useCase.toLowerCase();
+    if (/(medical|health|hospital|clinic|patient|appointment)/.test(lower)) {
+        return [
+            'verify_patient_identity',
+            'search_appointment_slots',
+            'book_appointment',
+            'reschedule_appointment',
+            'cancel_appointment',
+            'escalate_to_clinical_triage',
+        ];
+    }
+    if (/(billing|payment|refund|invoice|subscription|finance|bank|loan)/.test(lower)) {
+        return [
+            'lookup_account',
+            'get_invoice_status',
+            'create_payment_intent',
+            'issue_refund',
+            'escalate_to_billing_specialist',
+        ];
+    }
+    if (/(support|ticket|incident|helpdesk|customer support)/.test(lower)) {
+        return [
+            'lookup_customer_profile',
+            'search_knowledge_base',
+            'create_support_ticket',
+            'update_ticket_status',
+            'escalate_to_human_agent',
+        ];
+    }
+    if (/(sales|lead|qualification|demo|crm)/.test(lower)) {
+        return [
+            'lookup_company_profile',
+            'qualify_lead',
+            'create_crm_record',
+            'schedule_demo',
+            'handoff_to_account_exec',
+        ];
+    }
+    return ['lookup_context', 'execute_action', 'escalate_to_human'];
+}
+function addToolGuidanceToFlow(flow, selectedTools, suggestedToolSlots) {
+    const toolLine = selectedTools.length > 0
+        ? `Available tools for verification/execution: ${selectedTools.join(', ')}.`
+        : 'No tools are configured yet; do not claim tool-based verification. Ask for clarification or escalate when verification is required.';
+    const suggestionLine = selectedTools.length === 0 && suggestedToolSlots.length > 0
+        ? `Suggested tool slots to configure for this use case: ${suggestedToolSlots.join(', ')}.`
+        : undefined;
+    const existing = flow.defaultRolePrompt ?? '';
+    const lines = ['## Tool Availability', `- ${toolLine}`];
+    if (suggestionLine) {
+        lines.push(`- ${suggestionLine}`);
+    }
+    const section = `${existing}\n\n${lines.join('\n')}`;
+    return {
+        ...flow,
+        defaultRolePrompt: section.trim(),
+    };
+}
+async function discoverToolCandidates(cwd) {
+    const discovered = [];
+    try {
+        const configPath = existsSync(join(cwd, 'ariaflow.jsonc'))
+            ? join(cwd, 'ariaflow.jsonc')
+            : existsSync(join(cwd, 'ariaflow.json'))
+                ? join(cwd, 'ariaflow.json')
+                : undefined;
+        if (configPath) {
+            const loaded = await loadAriaflowConfigWithResult({
+                configPath,
+                silent: true,
+            });
+            discovered.push(...Object.keys(loaded.config.tools));
+        }
+    }
+    catch {
+        // Best-effort discovery only
+    }
+    const toolsDir = join(cwd, '.ariaflow', 'tools');
+    if (existsSync(toolsDir)) {
+        try {
+            for (const entry of readdirSync(toolsDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const toolJson = join(toolsDir, entry.name, 'tool.json');
+                if (existsSync(toolJson)) {
+                    discovered.push(entry.name);
+                }
+            }
+        }
+        catch {
+            // Best-effort discovery only
+        }
+    }
+    return uniqueStrings(discovered);
+}
+function buildPromptLayers(useCase, mode, selectedTools, suggestedToolSlots, clarifications) {
+    const toolList = selectedTools.length > 0 ? selectedTools.join(', ') : 'None configured';
+    const toolSuggestions = selectedTools.length === 0 && suggestedToolSlots.length > 0
+        ? ` Suggested tool slots: ${suggestedToolSlots.join(', ')}.`
+        : '';
+    const domainSafety = inferDomainSafetyAddendum(useCase);
+    const constraints = clarifications
+        .filter(item => /constraint|never do|compliance|safety/i.test(item.question))
+        .map(item => item.answer)
+        .join(' | ');
+    return {
+        identityAndScope: `You are an AriaFlow agent focused on this use case: ${useCase}. Prioritize task completion, clear user outcomes, and deterministic behavior for mode ${mode}.`,
+        safetyAndGuardrails: `Do not guess or invent facts. If uncertain, ask a clarifying question. Escalate or refuse unsafe requests. ${domainSafety ? `${domainSafety} ` : ''}${constraints ? `Additional constraints: ${constraints}.` : ''}`.trim(),
+        toolContract: `Use available tools to verify facts before answering. Selected tools: ${toolList}.${toolSuggestions} ${selectedTools.length > 0 ? 'Call tools when external verification or side effects are required.' : 'No tools are configured; do not claim tool-grounded verification until real tools are wired.'} If a tool fails, explain the limitation and propose the next safe step.`,
+        reasoningWorkflow: 'Ask one focused question at a time. Confirm critical fields before side effects. Do not mix tool transitions and user-facing prose in the same step.',
+        executionPolicy: mode === 'llm'
+            ? 'Operate as an LLM-first assistant with explicit tool checks before factual claims.'
+            : 'Operate as a flow-aware assistant. Keep SOP in nodes/transitions and enforce transition contracts.',
+        outputVerification: 'Keep responses concise, policy-compliant, and verifiable. Summarize decisions and ask for confirmation before final actions.',
+    };
+}
+function buildLayeredPromptMarkdown(agentName, layers) {
+    return [
+        `# ${agentName} System Prompt`,
+        '',
+        '## Identity and Scope',
+        layers.identityAndScope,
+        '',
+        '## Safety and Guardrails',
+        layers.safetyAndGuardrails,
+        '',
+        '## Tool Contract',
+        layers.toolContract,
+        '',
+        '## Reasoning Workflow',
+        layers.reasoningWorkflow,
+        '',
+        '## Execution Policy',
+        layers.executionPolicy,
+        '',
+        '## Output and Verification',
+        layers.outputVerification,
+        '',
+    ].join('\n');
+}
+function summarizeUseCaseForPrompt(useCase) {
+    const compact = useCase.replace(/\s+/g, ' ').trim();
+    if (compact.length <= 220) {
+        return compact;
+    }
+    const slice = compact.slice(0, 220);
+    const lastSpace = slice.lastIndexOf(' ');
+    const safe = lastSpace > 120 ? slice.slice(0, lastSpace) : slice;
+    return `${safe.trim()}...`;
+}
+function extractFlowTaskTitles(prompt) {
+    const titles = [];
+    const pattern = /^###\s*Task\s*\d+:\s*(.+)$/gm;
+    let match;
+    while ((match = pattern.exec(prompt)) !== null) {
+        const title = (match[1] ?? '').trim();
+        if (title.length > 0) {
+            titles.push(title);
+        }
+    }
+    return titles;
+}
+function extractSuccessCriteria(prompt) {
+    const marker = '# Success criteria WHEN you can move to next step';
+    const idx = prompt.indexOf(marker);
+    if (idx < 0) {
+        return [];
+    }
+    const tail = prompt.slice(idx + marker.length);
+    const lines = tail
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.startsWith('- '))
+        .map(line => line.slice(2).trim())
+        .filter(Boolean);
+    return uniqueStrings(lines);
+}
+function buildFlowBackedPromptMarkdown(agentName, useCase, layers, flow, selectedTools) {
+    const mainAgendaNode = flow.nodes.find(node => node.id === 'main_agenda')
+        ?? flow.nodes.find(node => node.name?.toLowerCase().includes('agenda'));
+    const transitionLines = (flow.transitions ?? []).map(transition => {
+        const label = transition.contract?.label?.trim() || `${transition.from} -> ${transition.to}`;
+        const event = transition.on ? `event=\`${transition.on}\`` : 'event=`<none>`';
+        const condition = transition.contract?.conditionText?.trim() || 'No explicit condition text.';
+        return `- ${label} (${event}): ${condition}`;
+    });
+    const toolLines = selectedTools.length > 0
+        ? selectedTools.map(tool => `- \`${tool}\``)
+        : ['- No concrete tools configured yet.'];
+    const mainAgendaPrompt = typeof mainAgendaNode?.prompt === 'string' ? mainAgendaNode.prompt : '';
+    const focusAreas = extractFlowTaskTitles(mainAgendaPrompt);
+    const successCriteria = extractSuccessCriteria(mainAgendaPrompt);
+    return [
+        `# ${agentName} System Prompt`,
+        '',
+        '## Mission',
+        summarizeUseCaseForPrompt(useCase),
+        '',
+        '## LLM Global Policy (Flow Derived)',
+        flow.defaultRolePrompt?.trim() || layers.identityAndScope,
+        '',
+        '## Conversation Focus Areas',
+        focusAreas.length > 0
+            ? focusAreas.map(item => `- ${item}`).join('\n')
+            : '- Collect intent, key details, and confirmation in deterministic sequence.',
+        '',
+        '## Completion Criteria',
+        successCriteria.length > 0
+            ? successCriteria.slice(0, 8).map(item => `- ${item}`).join('\n')
+            : '- Confirm required details before any side effects.',
+        '',
+        '## Tooling',
+        toolLines.join('\n'),
+        '',
+        '## Tool Contract',
+        layers.toolContract,
+        '',
+        '## Transition Contracts',
+        transitionLines.length > 0
+            ? transitionLines.join('\n')
+            : '- No transitions configured.',
+        '',
+        '## Safety and Guardrails',
+        layers.safetyAndGuardrails,
+        '',
+        '## Output and Verification',
+        layers.outputVerification,
+        '',
+    ].join('\n');
+}
+function buildPromptTypeScriptModule(constName, prompt) {
+    const serialized = JSON.stringify(prompt);
+    return `export const ${constName}SystemPrompt = ${serialized};\n\nexport default ${constName}SystemPrompt;\n`;
+}
+function buildBlueprintRfcMarkdown(title, blueprint, outputFiles) {
+    return [
+        `# RFC: ${title}`,
+        '',
+        `- Generated: ${blueprint.generationMeta.generatedAt}`,
+        `- Use case: ${blueprint.useCase}`,
+        `- Mode: ${blueprint.mode}`,
+        `- Target: ${blueprint.target}`,
+        '',
+        '## Selected Tools',
+        blueprint.selectedTools.length > 0 ? blueprint.selectedTools.map(tool => `- ${tool}`).join('\n') : '- None declared',
+        '',
+        '## Suggested Tool Slots',
+        blueprint.suggestedToolSlots.length > 0
+            ? blueprint.suggestedToolSlots.map(tool => `- ${tool}`).join('\n')
+            : '- None suggested',
+        '',
+        '## Prompt Layers',
+        Object.entries(blueprint.promptLayers).map(([key, value]) => `### ${key}\n${value}`).join('\n\n'),
+        '',
+        '## Generated Artifacts',
+        outputFiles.map(file => `- ${file}`).join('\n'),
+        '',
+        '## Eval Scenarios',
+        blueprint.evalPlan.scenarios.map(item => `- ${item}`).join('\n'),
+        '',
+    ].join('\n');
+}
+async function collectClarifications(maxQuestions) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return [];
+    }
+    const questions = [
+        'Who are the primary end users for this agent?',
+        'What are the top outcomes this agent must achieve?',
+        'List required tools or capabilities (comma-separated, optional):',
+        'Any hard safety or compliance constraints?',
+        'What should this agent never do?',
+    ];
+    const rl = createInterface({ input, output });
+    const answers = [];
+    const budget = Math.max(1, Math.min(maxQuestions, 6));
+    try {
+        for (let i = 0; i < budget && i < questions.length; i++) {
+            const question = questions[i];
+            const response = (await rl.question(`${question}\n> `)).trim();
+            if (response.length > 0) {
+                answers.push({ question, answer: response });
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return answers;
+}
+function printAgentHelp() {
+    console.log(`
+AriaFlow Agent Architect
+
+Usage:
+  ariaflow agent architect --use-case <text> [options]
+
+Generates:
+  - AgentBlueprint JSON
+  - Layered prompt artifacts
+  - Flow artifacts (for flow/hybrid modes)
+  - Typed code artifacts (for code/both targets)
+  - RFC with implementation instructions
+
+Options:
+  --use-case <text>         Use-case description (required)
+  --name <id>               Output id override (default: slugified use-case)
+  --mode <value>            llm | flow | hybrid (default: hybrid)
+  --target <value>          config | code | both (default: both)
+  --model <id>              Model id for LLM generation (default: gpt-5-mini)
+  --llm-driven              Use new LLM-driven analysis (analyzes use case, recommends tools, generates 6-layer prompts)
+  --detail-level <value>    simple | detailed (default: detailed) - simple shows only required tools
+  --direction <value>       inbound | outbound (default: inbound)
+  --agent-name <name>       Agent display name used in flow generation (default: Sam)
+  --context-file <path>     Additional context file (MD/TXT/YAML)
+  --timeout-ms <n>          LLM generation timeout in ms (default: 120000)
+  --interactive             Enable bounded follow-up clarification loop
+  --emit-rfc                Emit a generated RFC markdown file
+  --out-dir <path>          Output directory root (default: ./.ariaflow/generated)
+  --cwd <dir>               Base directory (default: current directory)
+  --force                   Overwrite existing output files
+
+Examples:
+  ariaflow agent architect --use-case "cake shop order taking" --llm-driven --detail-level simple
+  ariaflow agent architect --use-case "bakery inquiry agent" --llm-driven --mode flow
+  ariaflow agent architect --use-case "medical form intake" --llm-driven --emit-rfc
+`);
+}
+async function cmdAgentArchitect(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        printAgentHelp();
+        return;
+    }
+    let useCase;
+    let mode = 'hybrid';
+    let target = 'both';
+    let name;
+    let tools = [];
+    let model = 'gpt-5-mini';
+    let llmMode = 'hybrid';
+    let allowFlowFallback = false;
+    let direction = 'inbound';
+    let agentName = 'Sam';
+    let contextFile;
+    let timeoutMs;
+    let interactive = false;
+    let maxQuestions = 4;
+    let emitRfc = false;
+    let llmDriven = false;
+    let detailLevel = 'detailed';
+    let outDir = '.ariaflow/generated';
+    let cwd = process.cwd();
+    let force = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--use-case' && i + 1 < args.length) {
+            useCase = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--name' && i + 1 < args.length) {
+            name = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--mode' && i + 1 < args.length) {
+            const value = (args[i + 1] ?? '').trim().toLowerCase();
+            if (value === 'llm' || value === 'flow' || value === 'hybrid') {
+                mode = value;
+            }
+            else {
+                console.error(`\n❌ Invalid --mode value: ${args[i + 1]}`);
+                console.log('Allowed values: llm, flow, hybrid\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--target' && i + 1 < args.length) {
+            const value = (args[i + 1] ?? '').trim().toLowerCase();
+            if (value === 'config' || value === 'code' || value === 'both') {
+                target = value;
+            }
+            else {
+                console.error(`\n❌ Invalid --target value: ${args[i + 1]}`);
+                console.log('Allowed values: config, code, both\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--tools' && i + 1 < args.length) {
+            tools = uniqueStrings([...tools, ...parseCsv(args[i + 1] ?? '')]);
+            i++;
+            continue;
+        }
+        if (arg === '--llm') {
+            // Backward-compatible no-op: architect is LLM-required.
+            continue;
+        }
+        if (arg === '--model' && i + 1 < args.length) {
+            model = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--llm-mode' && i + 1 < args.length) {
+            const value = (args[i + 1] ?? '').trim().toLowerCase();
+            if (value === 'hybrid' || value === 'full') {
+                llmMode = value;
+            }
+            else {
+                console.error(`\n❌ Invalid --llm-mode value: ${args[i + 1]}`);
+                console.log('Allowed values: hybrid, full\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--allow-flow-fallback') {
+            allowFlowFallback = true;
+            continue;
+        }
+        if (arg === '--direction' && i + 1 < args.length) {
+            const value = (args[i + 1] ?? '').trim().toLowerCase();
+            if (value === 'inbound' || value === 'outbound') {
+                direction = value;
+            }
+            else {
+                console.error(`\n❌ Invalid --direction value: ${args[i + 1]}`);
+                console.log('Allowed values: inbound, outbound\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--agent-name' && i + 1 < args.length) {
+            agentName = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--context-file' && i + 1 < args.length) {
+            contextFile = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--timeout-ms' && i + 1 < args.length) {
+            const parsed = Number(args[i + 1]);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                console.error(`\n❌ Invalid --timeout-ms value: ${args[i + 1]}\n`);
+                process.exit(1);
+            }
+            timeoutMs = Math.floor(parsed);
+            i++;
+            continue;
+        }
+        if (arg === '--interactive') {
+            interactive = true;
+            continue;
+        }
+        if (arg === '--max-questions' && i + 1 < args.length) {
+            const parsed = Number(args[i + 1]);
+            if (!Number.isFinite(parsed) || parsed < 1 || parsed > 6) {
+                console.error(`\n❌ Invalid --max-questions value: ${args[i + 1]}`);
+                console.log('Allowed range: 1..6\n');
+                process.exit(1);
+            }
+            maxQuestions = Math.floor(parsed);
+            i++;
+            continue;
+        }
+        if (arg === '--emit-rfc') {
+            emitRfc = true;
+            continue;
+        }
+        if (arg === '--llm-driven') {
+            llmDriven = true;
+            continue;
+        }
+        if (arg === '--detail-level' && i + 1 < args.length) {
+            const value = (args[i + 1] ?? '').trim().toLowerCase();
+            if (value === 'simple' || value === 'detailed') {
+                detailLevel = value;
+            }
+            else {
+                console.error(`\n❌ Invalid --detail-level value: ${args[i + 1]}`);
+                console.log('Allowed values: simple, detailed\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--out-dir' && i + 1 < args.length) {
+            outDir = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--cwd' && i + 1 < args.length) {
+            cwd = resolve(args[i + 1]);
+            i++;
+            continue;
+        }
+        if (arg === '--force') {
+            force = true;
+            continue;
+        }
+    }
+    if (!useCase || useCase.trim().length === 0) {
+        console.error('\n❌ Missing required --use-case <text>\n');
+        printAgentHelp();
+        process.exit(1);
+    }
+    if (llmDriven) {
+        try {
+            const result = await runArchitect({
+                useCase,
+                mode,
+                target,
+                name,
+                model,
+                contextText: contextFile ? readFileSync(contextFile.startsWith('/') ? contextFile : resolve(cwd, contextFile), 'utf8') : undefined,
+                timeoutMs,
+                interactive,
+                detailLevel,
+            });
+            const artifactRoot = outDir.startsWith('/') ? outDir : resolve(cwd, outDir);
+            const blueprintId = result.blueprint.id;
+            console.log('\n✅ LLM-Driven Agent Architect completed');
+            console.log(`   Blueprint ID: ${blueprintId}`);
+            console.log(`   Domain: ${result.blueprint.domainAnalysis.domain}`);
+            console.log(`   Tools recommended: ${result.blueprint.selectedTools.length}`);
+            const writtenFiles = [];
+            if (result.artifacts.prompt) {
+                const promptPath = join(artifactRoot, 'prompts', `${blueprintId}.system.md`);
+                ensureWritableFile(promptPath, result.artifacts.prompt, force);
+                writtenFiles.push(promptPath);
+            }
+            if (result.artifacts.rfc) {
+                const rfcPath = join(artifactRoot, 'rfcs', `RFC_${blueprintId.toUpperCase().replace(/-/g, '_')}.md`);
+                ensureWritableFile(rfcPath, result.artifacts.rfc, force);
+                writtenFiles.push(rfcPath);
+            }
+            if (result.artifacts.code?.prompt) {
+                const codePath = join(artifactRoot, 'code', 'prompts', `${blueprintId}.prompt.ts`);
+                ensureWritableFile(codePath, result.artifacts.code.prompt, force);
+                writtenFiles.push(codePath);
+            }
+            if (result.artifacts.flow) {
+                const flowPath = join(artifactRoot, 'flow', `${blueprintId}.json`);
+                ensureWritableFile(flowPath, `${JSON.stringify(result.artifacts.flow, null, 2)}\n`, force);
+                writtenFiles.push(flowPath);
+            }
+            if (result.artifacts.code?.flow) {
+                const flowTsPath = join(artifactRoot, 'code', 'flows', `${blueprintId}.flow.ts`);
+                ensureWritableFile(flowTsPath, result.artifacts.code.flow, force);
+                writtenFiles.push(flowTsPath);
+            }
+            const blueprintPath = join(artifactRoot, 'blueprints', `${blueprintId}.blueprint.json`);
+            ensureWritableFile(blueprintPath, `${JSON.stringify(result.blueprint, null, 2)}\n`, force);
+            writtenFiles.push(blueprintPath);
+            console.log('\nArtifacts:');
+            for (const file of writtenFiles) {
+                console.log(`   - ${file}`);
+            }
+            console.log('\nSuggested next steps:');
+            console.log('  1. Review the generated RFC for implementation guidance');
+            console.log('  2. Implement the recommended tools');
+            console.log('  3. Test with the evaluation scenarios\n');
+            return;
+        }
+        catch (error) {
+            console.error('\n❌ LLM-Driven Architect failed:', error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    }
+    if (interactive && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+        console.log('\n⚠️  Interactive mode requested but no TTY detected. Continuing in non-interactive mode.');
+        interactive = false;
+    }
+    const clarifications = interactive ? await collectClarifications(maxQuestions) : [];
+    const clarificationToolLine = clarifications
+        .find(item => /required tools|capabilities/i.test(item.question))
+        ?.answer;
+    if (clarificationToolLine) {
+        tools = uniqueStrings([...tools, ...parseCsv(clarificationToolLine)]);
+    }
+    if (tools.length === 0) {
+        tools = await discoverToolCandidates(cwd);
+    }
+    const suggestedToolSlots = inferSuggestedToolSlots(useCase);
+    const contextParts = [];
+    if (contextFile) {
+        const resolvedContextPath = contextFile.startsWith('/') ? contextFile : resolve(cwd, contextFile);
+        contextParts.push(readFileSync(resolvedContextPath, 'utf8'));
+    }
+    if (clarifications.length > 0) {
+        contextParts.push(`Interactive clarifications:\n${clarifications.map(item => `- ${item.question} ${item.answer}`).join('\n')}`);
+    }
+    const contextText = contextParts.length > 0 ? contextParts.join('\n\n') : undefined;
+    let flow;
+    let flowFallbackUsed = false;
+    let flowFallbackReason;
+    if (mode !== 'llm') {
+        let generatedFlow;
+        try {
+            generatedFlow = await generateFlowTemplateWithLLM({
+                useCase,
+                direction,
+                agentName,
+                model,
+                llmMode,
+                contextText,
+                timeoutMs,
+            });
+        }
+        catch (error) {
+            if (!allowFlowFallback) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`LLM flow generation failed and fallback is disabled. Reason: ${reason}\n` +
+                    'Re-run with --allow-flow-fallback to scaffold deterministic flow structure only.');
+            }
+            flowFallbackUsed = true;
+            flowFallbackReason = error instanceof Error ? error.message : String(error);
+            console.log('\n⚠️  LLM flow generation failed. Applying deterministic flow structure fallback (--allow-flow-fallback).');
+            generatedFlow = generateFlowTemplate({
+                useCase,
+                direction,
+                agentName,
+            });
+        }
+        flow = normalizeFlowDraft(addTransitionGuidance(addToolGuidanceToFlow(generatedFlow, tools, suggestedToolSlots)));
+    }
+    const blueprintId = toSlug(name ?? useCase);
+    const displayName = name ? toTitleCase(name) : toTitleCase(blueprintId);
+    const promptLayers = buildPromptLayers(useCase, mode, tools, suggestedToolSlots, clarifications);
+    const promptMarkdown = flow
+        ? buildFlowBackedPromptMarkdown(displayName, useCase, promptLayers, flow, tools)
+        : buildLayeredPromptMarkdown(displayName, promptLayers);
+    const promptConstName = toTsConstCase(blueprintId);
+    const blueprint = {
+        id: blueprintId,
+        name: displayName,
+        useCase,
+        mode,
+        target,
+        selectedTools: tools,
+        suggestedToolSlots,
+        promptLayers,
+        flowPlan: flow
+            ? {
+                id: flow.id ?? `${blueprintId}-flow`,
+                entry: flow.entry ?? 'start',
+                nodeIds: flow.nodes.map(node => node.id),
+                transitionEvents: (flow.transitions ?? [])
+                    .map(transition => transition.on)
+                    .filter((value) => typeof value === 'string' && value.length > 0),
+            }
+            : undefined,
+        evalPlan: {
+            scenarios: [
+                'happy_path',
+                'ambiguous_user_intent',
+                'tool_failure_path',
+                'policy_refusal_or_escalation',
+            ],
+        },
+        generationMeta: {
+            generatedAt: new Date().toISOString(),
+            model,
+            llmRequired: true,
+            llmEnabled: true,
+            llmMode,
+            fallbackUsed: flowFallbackUsed,
+            fallbackType: flowFallbackUsed ? 'flow-structure-only' : undefined,
+            fallbackReason: flowFallbackReason,
+            interactive,
+            clarificationCount: clarifications.length,
+            clarifications,
+        },
+    };
+    const artifactRoot = outDir.startsWith('/') ? outDir : resolve(cwd, outDir);
+    const writtenFiles = [];
+    const promptFilesForLint = [];
+    const blueprintPath = join(artifactRoot, 'blueprints', `${blueprintId}.blueprint.json`);
+    ensureWritableFile(blueprintPath, `${JSON.stringify(blueprint, null, 2)}\n`, force);
+    writtenFiles.push(blueprintPath);
+    if (target === 'config' || target === 'both') {
+        const promptPath = join(artifactRoot, 'prompts', `${blueprintId}.system.md`);
+        ensureWritableFile(promptPath, promptMarkdown, force);
+        writtenFiles.push(promptPath);
+        promptFilesForLint.push(promptPath);
+        if (flow) {
+            const flowPath = join(artifactRoot, 'flow', `${blueprintId}.json`);
+            ensureWritableFile(flowPath, `${JSON.stringify(flow, null, 2)}\n`, force);
+            writtenFiles.push(flowPath);
+        }
+    }
+    if (target === 'code' || target === 'both') {
+        const promptTsPath = join(artifactRoot, 'code', 'prompts', `${blueprintId}.prompt.ts`);
+        ensureWritableFile(promptTsPath, buildPromptTypeScriptModule(promptConstName, promptMarkdown), force);
+        writtenFiles.push(promptTsPath);
+        if (flow) {
+            const flowTsPath = join(artifactRoot, 'code', 'flows', `${blueprintId}.flow.ts`);
+            const flowTs = emitFlowTypeScriptModule(flow, { constName: `${promptConstName}Flow` });
+            ensureWritableFile(flowTsPath, flowTs, force);
+            writtenFiles.push(flowTsPath);
+        }
+    }
+    if (emitRfc) {
+        const rfcPath = join(artifactRoot, 'rfcs', `RFC_${blueprintId.toUpperCase().replace(/-/g, '_')}.md`);
+        const rfcMarkdown = buildBlueprintRfcMarkdown(displayName, blueprint, writtenFiles);
+        ensureWritableFile(rfcPath, rfcMarkdown, force);
+        writtenFiles.push(rfcPath);
+    }
+    if (promptFilesForLint.length > 0) {
+        const issues = [];
+        const triageRuleIds = new Set([
+            'triage-missing-routing-directive',
+            'triage-user-leak-risk',
+            'triage-not-structured',
+            'sop-in-prompt',
+            'prompt-too-long',
+        ]);
+        for (const promptPath of promptFilesForLint) {
+            const lintResult = lintPrompts({ cwd: artifactRoot, path: promptPath });
+            for (const issue of lintResult.issues) {
+                if (triageRuleIds.has(issue.ruleId)) {
+                    continue;
+                }
+                issues.push(issue);
+            }
+        }
+        if (issues.length > 0) {
+            console.log('\n❌ Generated prompts failed lint gate:\n');
+            for (const issue of issues) {
+                const relFile = issue.file.startsWith(artifactRoot)
+                    ? `.${issue.file.slice(artifactRoot.length)}`
+                    : issue.file;
+                console.log(`- [${issue.severity}] ${issue.ruleId}: ${issue.message}`);
+                console.log(`  File: ${relFile}`);
+            }
+            process.exit(1);
+        }
+    }
+    console.log('\n✅ Agent blueprint generated:');
+    console.log(`   ID: ${blueprintId}`);
+    console.log(`   Mode: ${mode}`);
+    console.log(`   Target: ${target}`);
+    console.log(`   LLM generation: required (${model}, ${llmMode})`);
+    if (flowFallbackUsed) {
+        console.log('   Flow fallback: deterministic structure-only');
+    }
+    if (interactive) {
+        console.log(`   Clarification loop: ${clarifications.length} answer(s) captured (max ${maxQuestions})`);
+    }
+    console.log('\nArtifacts:');
+    for (const file of writtenFiles) {
+        console.log(`   - ${file}`);
+    }
+    console.log('\nSuggested next steps:');
+    console.log('  1. Review generated blueprint and prompt layers');
+    console.log('  2. Run domain transcripts against generated artifacts');
+    console.log('  3. Add or tune tool contracts before production rollout\n');
+}
+async function cmdFlowGenerate(args) {
+    let useCase;
+    let flowId;
+    let direction = 'inbound';
+    let agentName;
+    let model = 'gpt-5-mini';
+    let llmMode = 'hybrid';
+    let timeoutMs;
+    let useLlm = false;
+    let contextFile;
+    let outPath;
+    let outTsPath;
+    let tsConstName;
+    let cwd = process.cwd();
+    let force = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--use-case' && i + 1 < args.length) {
+            useCase = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--id' && i + 1 < args.length) {
+            flowId = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--direction' && i + 1 < args.length) {
+            const value = (args[i + 1] ?? '').trim().toLowerCase();
+            if (value === 'inbound' || value === 'outbound') {
+                direction = value;
+            }
+            else {
+                console.error(`\n❌ Invalid --direction value: ${args[i + 1]}`);
+                console.log('Allowed values: inbound, outbound\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--agent-name' && i + 1 < args.length) {
+            agentName = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--model' && i + 1 < args.length) {
+            model = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--llm-mode' && i + 1 < args.length) {
+            const mode = (args[i + 1] ?? '').trim().toLowerCase();
+            if (mode === 'hybrid' || mode === 'full') {
+                llmMode = mode;
+            }
+            else {
+                console.error(`\n❌ Invalid --llm-mode value: ${args[i + 1]}`);
+                console.log('Allowed values: hybrid, full\n');
+                process.exit(1);
+            }
+            i++;
+            continue;
+        }
+        if (arg === '--context-file' && i + 1 < args.length) {
+            contextFile = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--timeout-ms' && i + 1 < args.length) {
+            const parsed = Number(args[i + 1]);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                console.error(`\n❌ Invalid --timeout-ms value: ${args[i + 1]}\n`);
+                process.exit(1);
+            }
+            timeoutMs = Math.floor(parsed);
+            i++;
+            continue;
+        }
+        if (arg === '--out' && i + 1 < args.length) {
+            outPath = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--out-ts' && i + 1 < args.length) {
+            outTsPath = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--ts-const' && i + 1 < args.length) {
+            tsConstName = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--cwd' && i + 1 < args.length) {
+            cwd = resolve(args[i + 1]);
+            i++;
+            continue;
+        }
+        if (arg === '--force') {
+            force = true;
+        }
+        if (arg === '--llm') {
+            useLlm = true;
+        }
+    }
+    if (!useCase || useCase.trim().length === 0) {
+        console.error('\n❌ Missing required --use-case <text>\n');
+        printFlowHelp();
+        process.exit(1);
+    }
+    const contextText = contextFile
+        ? readFileSync(contextFile.startsWith('/') ? contextFile : resolve(cwd, contextFile), 'utf8')
+        : undefined;
+    const flow = useLlm
+        ? await generateFlowTemplateWithLLM({
+            useCase,
+            flowId,
+            direction,
+            agentName,
+            model,
+            llmMode,
+            contextText,
+            timeoutMs,
+        })
+        : generateFlowTemplate({
+            useCase,
+            flowId,
+            direction,
+            agentName,
+        });
+    const output = `${JSON.stringify(flow, null, 2)}\n`;
+    const tsOutput = emitFlowTypeScriptModule(flow, { constName: tsConstName });
+    if (!outPath && !outTsPath) {
+        process.stdout.write(output);
+        return;
+    }
+    const writtenFiles = [];
+    if (outPath) {
+        const target = outPath.startsWith('/') ? outPath : resolve(cwd, outPath);
+        if (existsSync(target) && !force) {
+            console.error(`\n❌ File already exists: ${target}`);
+            console.log('Use --force to overwrite.\n');
+            process.exit(1);
+        }
+        const parentDir = dirname(target);
+        if (!existsSync(parentDir)) {
+            mkdirSync(parentDir, { recursive: true });
+        }
+        writeFileSync(target, output, 'utf8');
+        writtenFiles.push(target);
+    }
+    if (outTsPath) {
+        const targetTs = outTsPath.startsWith('/') ? outTsPath : resolve(cwd, outTsPath);
+        if (existsSync(targetTs) && !force) {
+            console.error(`\n❌ File already exists: ${targetTs}`);
+            console.log('Use --force to overwrite.\n');
+            process.exit(1);
+        }
+        const parentDirTs = dirname(targetTs);
+        if (!existsSync(parentDirTs)) {
+            mkdirSync(parentDirTs, { recursive: true });
+        }
+        writeFileSync(targetTs, tsOutput, 'utf8');
+        writtenFiles.push(targetTs);
+    }
+    console.log('\n✅ Flow template generated:');
+    for (const file of writtenFiles) {
+        console.log(`   - ${file}`);
+    }
+    if (useLlm) {
+        console.log(`   Model: ${model}`);
+        console.log(`   LLM mode: ${llmMode}`);
+    }
+    console.log('\nSuggested next steps:');
+    console.log('  1. Replace Task sections with domain-specific questions and data rules');
+    console.log('  2. (Optional) Add explicit transition tools if you need custom transition payload logic');
+    console.log('  3. Run: ariaflow validate\n');
+}
+function printFlowHelp() {
+    console.log(`
+AriaFlow Flow Generator
+
+Usage:
+  ariaflow flow generate --use-case <text> [--id <flow-id>] [--direction inbound|outbound] [--agent-name <name>] [--llm --model <id> --llm-mode hybrid|full] [--context-file <path>] [--timeout-ms <n>] [--out <path>] [--out-ts <path>] [--ts-const <name>] [--cwd <dir>] [--force]
+
+Generates a production-style flow JSON scaffold with:
+- global role prompt
+- start/main/summary/end node prompts
+- transition contract metadata (label, conditionText, toolOnly, requiresUserTurn)
+- optional LLM-authored prompt blocks (--llm)
+- default LLM mode is hybrid: static scaffold + variable domain blocks
+
+Options:
+  --use-case <text>      Use-case description (required)
+  --id <flow-id>         Flow id override (optional)
+  --direction <value>    inbound | outbound (default: inbound)
+  --agent-name <name>    Agent name used in global prompt (default: Sam)
+  --llm                  Use an LLM model to generate global/main-agenda prompts
+  --model <id>           OpenAI model id for --llm (default: gpt-5-mini; e.g. gpt-5-mini, gpt-4.1, openai:gpt-4.1)
+  --llm-mode <mode>      hybrid | full (default: hybrid)
+  --context-file <path>  Additional input context (YAML/MD/TXT) for --llm generation
+  --timeout-ms <n>       LLM generation timeout in ms (default: 45000)
+  --out <path>           Write JSON flow output to file
+  --out-ts <path>        Write typed TypeScript flow module for code-first agents
+  --ts-const <name>      Constant name for --out-ts module (default: generatedFlow)
+  --cwd <dir>            Base directory for relative --out paths
+  --force                Overwrite existing output file
+
+Examples:
+  ariaflow flow generate --use-case "hr technical screening"
+  ariaflow flow generate --use-case "medical appointment scheduling" --out ./.ariaflow/flow/appointments.json --out-ts ./src/flows/appointments-flow.ts
+  ariaflow flow generate --use-case "sales with leads extraction and research" --llm --model gpt-5-mini --llm-mode hybrid --out ./.ariaflow/flow/sales.json
+  ariaflow flow generate --use-case "form filling from yaml" --llm --model gpt-5-mini --context-file ./.ariaflow/data/schedule_form.yaml
 `);
 }
 main().catch((error) => {