@relipa/ai-flow-kit 0.0.9-beta.1 → 0.1.0-beta.0

package/bin/aiflow.js

@@ -1,475 +1,525 @@
-#!/usr/bin/env node
-
-const { program } = require('commander');
-const chalk = require('chalk');
-const packageJson = require('../package.json');
-const initCommand     = require('../scripts/init');
-const updateCommand   = require('../scripts/update');
-const doctorCommand   = require('../scripts/doctor');
-const useCommand      = require('../scripts/use');
-const TaskDetector    = require('../scripts/detect');
-const validateCommand = require('../scripts/validate');
-const memoryCommand   = require('../scripts/memory');
-const contextCommand  = require('../scripts/context');
-const promptCommand   = require('../scripts/prompt');
-const removeCommand   = require('../scripts/remove');
-const guideCommand    = require('../scripts/guide');
-const telemetryCommand= require('../scripts/telemetry/cli');
-const taskCommand     = require('../scripts/task');
-const checkpointCommand = require('../scripts/checkpoint');
-const { record }      = require('../scripts/telemetry/record');
-const { updateTaskGateState } = require('../scripts/task');
-
-// ── DEPRECATION WARNING ───────────────────────────────────────
-if (!process.env.AIFLOW_IS_AK) {
-    console.warn(chalk.yellow('\n⚠ Warning: "aiflow" command is deprecated and will be removed in future versions.'));
-    console.warn(chalk.yellow('Please use the shorter "ak" command instead.\n'));
-}
-
-program
-    .version(packageJson.version)
-    .description('AI Flow Kit CLI - AI-powered development workflows for teams');
-
-// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
-// We intercept raw argv here so we can catch --version, --help,
-// and invalid commands *before* Commander exits the process.
-// Also alias `-v` to commander's `-V` at the root only — subcommands still
-// keep `-v` as `--verbose`. And alias `--fw` to `--framework`.
-(() => {
-    if (process.argv[2] === '-v') process.argv[2] = '-V';
-    for (let i = 3; i < process.argv.length; i++) {
-        if (process.argv[i] === '--fw') process.argv[i] = '--framework';
-    }
-    const args = process.argv.slice(2);
-    let cmd = 'help';
-    if (args.length > 0) {
-        let first = args[0];
-
-        // 1. Phân giải alias cho root commands
-        const aliases = {
-            'i': 'init',
-            'u': 'use',
-            'p': 'prompt',
-            'd': 'detect',
-            't': 'task',
-            'ctx': 'context',
-            'cp': 'checkpoint',
-            'vl': 'validate',
-            'mem': 'memory',
-            'g': 'guide',
-            'rm': 'remove',
-            'up': 'update',
-            'sync': 'sync-skills',
-            'dr': 'doctor',
-            'tel': 'telemetry'
-        };
-        if (aliases[first]) {
-            first = aliases[first];
-        }
-
-        if (['-V', '-v', '--version'].includes(first)) {
-            cmd = 'version';
-        } else if (['-h', '--help'].includes(first)) {
-            cmd = 'help';
-        } else if (first.startsWith('-')) {
-            cmd = 'unknown_flag';
-            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
-        } else if (first === 'memory') {
-            const sec = args[1];
-            // Phân giải alias cho memory subcommands
-            let sub = sec;
-            if (sec && !sec.startsWith('-')) {
-                const memAliases = {
-                    's': 'save',
-                    'g': 'get',
-                    'ls': 'list',
-                    'sr': 'search',
-                    'd': 'delete',
-                    'cl': 'clear'
-                };
-                if (memAliases[sec]) sub = memAliases[sec];
-                cmd = `memory.${sub}`;
-            } else {
-                cmd = 'memory';
-            }
-        } else if (first === 'task') {
-            const sec = args[1];
-            // Phân giải alias subcommand của task
-            let sub = sec;
-            if (sec && !sec.startsWith('-')) {
-                const subAliases = {
-                    'st': 'status',
-                    'ls': 'list',
-                    'p': 'pause',
-                    'sw': 'switch',
-                    'r': 'resume',
-                    'rst': 'reset',
-                    'rm': 'remove',
-                    'n': 'next'
-                };
-                if (subAliases[sec]) sub = subAliases[sec];
-                cmd = `task.${sub}`;
-            } else {
-                cmd = 'task';
-            }
-        } else {
-            cmd = first;
-            if (args.includes('--help') || args.includes('-h')) {
-                cmd = `${first}.help`;
-            }
-        }
-    }
-    // Record everything except telemetry and gate actions (gate records its own rich event)
-    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
-        record('command.invoked', { command: cmd });
-    }
-})();
-
-
-// ── init ──────────────────────────────────────────────────────
-program
-    .command('init')
-    .alias('i')
-    .description('Initialize AI Flow Kit in your project')
-    .option('-f, --framework <types>', 'framework(s), comma-separated (e.g. spring-boot,reactjs)')
-    .option('-a, --adapter <types>', 'adapter(s), comma-separated (e.g. backlog,jira)')
-    .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
-    .option('--with-rtk', 'force enable RTK token compression hook')
-    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
-    .action((options) => {
-        options.frameworks = options.framework
-            ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
-            : [];
-        options.adapters = options.adapter
-            ? options.adapter.split(',').map(s => s.trim()).filter(Boolean)
-            : [];
-        options.aiTools = options.env
-            ? options.env.split(',').map(s => s.trim()).filter(Boolean)
-            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
-
-        initCommand(options);
-    });
-
-// ── use ───────────────────────────────────────────────────────
-program
-    .command('use [target]')
-    .alias('u')
-    .description('Load context from ticket, version, or file')
-    .option('-m, --manual', 'manual context entry')
-    .option('-f, --file <path>', 'load from file')
-    .option('-s, --save <name>', 'save as named context')
-    .option('-c, --coms', 'load all comments (alias for --with-comments)')
-    .option('--with-comments', 'load all comments')
-    .option('--cid <id>', 'load a specific comment by ID')
-    .option('--clast <n>', 'load the last N comments', parseInt)
-    .option('--cfrom <id>', 'load comments from ID N onward', parseInt)
-    .option('--cto <id>', 'load comments up to ID N', parseInt)
-    .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
-    .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
-    .action((target, options) => {
-        useCommand(target, options);
-    });
-
-// ── prompt ────────────────────────────────────────────────────
-program
-    .command('prompt [type]')
-    .alias('p')
-    .description('Generate AI prompt with context and rules')
-    .option('-l, --list', 'list available prompt types')
-    .option('-o, --output <file>', 'save to file')
-    .option('-L, --lang <lang>', 'language: english (default) or vietnamese')
-    .option('-d, --detail <level>', 'detail level: minimal | standard (default) | comprehensive')
-    .action((type, options) => {
-        promptCommand(type, options);
-    });
-
-// ── detect ────────────────────────────────────────────────────
-program
-    .command('detect [description]')
-    .alias('d')
-    .description('Auto-detect task type from description')
-    .option('-v, --verbose', 'show detection details')
-    .option('-t, --threshold <number>', 'confidence threshold (0-100)')
-    .action((description, options) => {
-        const detector = new TaskDetector();
-        const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
-        const result = detector.detect(description, threshold);
-        console.log(chalk.cyan('\nTask Detection Results:\n'));
-        console.log(detector.formatOutput(result, options.verbose));
-    });
-
-// ── task ─────────────────────────────────────────────────────
-const taskCmd = program.command('task').alias('t').description('Manage multiple tasks — pause, switch, resume');
-
-taskCmd
-    .command('status')
-    .alias('st')
-    .description('Show active task and pending tasks')
-    .action(() => { taskCommand('status'); });
-
-taskCmd
-    .command('list')
-    .alias('ls')
-    .description('List all saved tasks')
-    .action(() => { taskCommand('list'); });
-
-taskCmd
-    .command('pause')
-    .alias('p')
-    .description('Pause current task and save progress')
-    .option('-n, --note <text>', 'note about why you are pausing')
-    .action((opts) => { taskCommand('pause', { note: opts.note }); });
-
-taskCmd
-    .command('switch <ticket-id>')
-    .alias('sw')
-    .description('Pause current task and switch to another')
-    .action((ticketId) => { taskCommand('switch', { taskId: ticketId }); });
-
-taskCmd
-    .command('resume <ticket-id>')
-    .alias('r')
-    .description('Resume a paused task')
-    .action((ticketId) => { taskCommand('resume', { taskId: ticketId }); });
-
-taskCmd
-    .command('reset <ticket-id>')
-    .alias('rst')
-    .description('Reset task to Gate 1 (keeps ticket context, clears gate progress)')
-    .action((ticketId) => { taskCommand('reset', { taskId: ticketId }); });
-
-taskCmd
-    .command('remove <ticket-id>')
-    .alias('rm')
-    .description('Permanently delete all saved data for a task')
-    .action((ticketId) => { taskCommand('remove', { taskId: ticketId }); });
-
-taskCmd
-    .command('next')
-    .alias('n')
-    .description('Approve current gate and prepare next session (saves state for resume)')
-    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
-    .action((opts) => {
-        taskCommand('next', { taskId: opts.ticket });
-    });
-
-// ── context ───────────────────────────────────────────────────
-program
-    .command('context [action]')
-    .alias('ctx')
-    .description('Manage task contexts (list|show|save <name>|clear)')
-    .option('-s, --save <name>', 'save current context with name')
-    .option('-l, --load <name>', 'load saved context by name')
-    .option('-d, --delete <name>', 'delete saved context')
-    .option('--clear', 'clear all saved contexts')
-    .option('--show', 'show current context')
-    .action((action, options) => {
-        contextCommand(action, options);
-    });
-
-// ── checkpoint ────────────────────────────────────────────────
-program
-    .command('checkpoint')
-    .alias('cp')
-    .description('Record token usage checkpoint (called by AI during gate work)')
-    .requiredOption('-g, --gate <n>', 'gate number (1–5)', parseInt)
-    .requiredOption('-s, --step <name>', 'step name (e.g. "tests-written")')
-    .requiredOption('-n, --tokens <n>', 'estimated token count', parseInt)
-    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
-    .action((opts) => {
-        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
-    });
-
-// ── validate ──────────────────────────────────────────────────
-program
-    .command('validate <file>')
-    .alias('vl')
-    .description('Validate output against team rules')
-    .option('-r, --ruleset <set>', 'rule set: default | strict | lenient', 'default')
-    .option('-v, --verbose', 'detailed report')
-    .option('-x, --fix', 'auto-fix trailing whitespace')
-    .action((file, options) => {
-        validateCommand(file, {
-            ruleset: options.ruleset,
-            verbose: options.verbose,
-            fix: options.fix
-        });
-    });
-
-// ── memory ────────────────────────────────────────────────────
-// Sub-commands to avoid the ambiguous "memory <action> --save key" pattern
-const memCmd = program.command('memory').alias('mem').description('Manage team knowledge and memory');
-
-memCmd
-    .command('save <key> <value>')
-    .alias('s')
-    .description('Save a memory entry')
-    .action((key, value) => { memoryCommand('save', { key, value }); });
-
-memCmd
-    .command('get <key>')
-    .alias('g')
-    .description('Retrieve a memory entry')
-    .action((key) => { memoryCommand('get', { key }); });
-
-memCmd
-    .command('list')
-    .alias('ls')
-    .description('List all memories')
-    .action(() => { memoryCommand('list'); });
-
-memCmd
-    .command('search <query>')
-    .alias('sr')
-    .description('Search memories by keyword')
-    .action((query) => { memoryCommand('search', { query }); });
-
-memCmd
-    .command('delete <key>')
-    .alias('d')
-    .description('Delete a memory entry')
-    .action((key) => { memoryCommand('delete', { key }); });
-
-memCmd
-    .command('clear')
-    .alias('cl')
-    .description('Clear all memories')
-    .action(() => { memoryCommand('clear'); });
-
-// ── guide ─────────────────────────────────────────────────────
-program
-    .command('guide')
-    .alias('g')
-    .description('Show quickstart guide, architecture, and command reference')
-    .option('-f, --flow', 'show architecture & flow diagram only')
-    .option('-c, --commands', 'show command reference only')
-    .action((options) => {
-        guideCommand(options);
-    });
-
-// ── telemetry feedback helper ─────────────────────────────────
-function showTelResult(result, label) {
-    try {
-        if (!result) return;
-        if (result.ok) {
-            console.log(chalk.green(`  [tel] ✓ ${label} logged`));
-        } else if (result.reason === 'disabled') {
-            console.log(chalk.yellow(`  [tel] ⚠ skipped — telemetry is disabled (run 'aiflow telemetry enable')`));
-        } else if (result.reason === 'opted-out') {
-            console.log(chalk.yellow(`  [tel] ⚠ skipped — repo has .aiflow/no-telemetry opt-out`));
-        } else if (result.reason === 'no-url') {
-            console.log(chalk.yellow(`  [tel] ⚠ skipped — no server URL configured (run 'aiflow telemetry enable')`));
-        } else if (result.error) {
-            console.log(chalk.yellow(`  [tel] ⚠ error logging '${label}': ${result.error}`));
-        }
-    } catch (e) { /* never block main flow */ }
-}
-
-// ── gate (telemetry for gate workflow events) ─────────────────
-program
-    .command('gate <number> <action>')
-    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
-    .option('--ticket <id>', 'ticket ID')
-    .option('--ai-tool <tool>', 'AI tool name')
-    .action((number, action, options) => {
-        const gateNum = parseInt(number);
-        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
-        if (!['start', 'approved'].includes(action)) return;
-
-        const ticketId = options.ticket || '';
-
-        const telResult = record(`gate.${action}`, {
-            gate: gateNum,
-            ticket_id: ticketId,
-            command: `gate${gateNum}.${action}`,
-            ai_tool: options.aiTool || ''
-        });
-        showTelResult(telResult, `gate${gateNum}.${action}`);
-
-        // Keep task-state.json currentGate in sync (silent — never blocks the AI)
-        if (ticketId) {
-            updateTaskGateState(ticketId, gateNum, action).catch(() => {});
-        }
-
-        if (action === 'approved') {
-            console.log(chalk.cyan(`\n  Gate ${gateNum} approved!`));
-            console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
-            console.log(chalk.gray(`  Run: aiflow task next${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
-            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
-        }
-    });
-
-// ── remove ────────────────────────────────────────────────────
-program
-    .command('remove')
-    .alias('rm')
-    .description('Remove ai-flow-kit from project, a cached version, or uninstall globally')
-    .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
-    .option('-g, --global', 'uninstall the global npm package (removes `aiflow` command)')
-    .action((options) => {
-        removeCommand(options);
-    });
-
-// ── update ────────────────────────────────────────────────────
-program
-    .command('update')
-    .alias('up')
-    .description('Update to latest version')
-    .option('-f, --force', 'force update even if already on latest')
-    .action((options) => {
-        updateCommand(options);
-    });
-
-// ── sync-skills ───────────────────────────────────────────────
-program
-    .command('sync-skills')
-    .alias('sync')
-    .description('Manually synchronize AI Instruction files with local custom skills')
-    .action(async () => {
-        const projectDir = process.cwd();
-        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
-        const fs = require('fs-extra');
-        const path = require('path');
-        const chalk = require('chalk');
-
-        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
-        if (!(await fs.pathExists(stateFile))) {
-            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
-            return;
-        }
-
-        const state = await fs.readJson(stateFile);
-        const frameworks = state.frameworks || [];
-        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
-
-        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
-        for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
-        }
-        await ensureAiflowGitignored(projectDir);
-        console.log(chalk.green('✨ Sync completed!'));
-    });
-
-// ── doctor ────────────────────────────────────────────────────
-program
-    .command('doctor')
-    .alias('dr')
-    .description('Health check of AI Flow Kit setup')
-    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
-    .option('-v, --verbose', 'detailed output')
-    .action((opts) => {
-        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
-    });
-
-// ── telemetry ──────────────────────────────────────────────────
-program
-    .command('telemetry [action]')
-    .alias('tel')
-    .description('Manage telemetry logging (enable|disable|status|log)')
-    .option('--event <event>', 'event name (for log action)')
-    .option('--detail <detail>', 'detail string (for log action)')
-    .action((action, options) => {
-        telemetryCommand(action || 'status', options);
-    });
-
-program.parse(process.argv);
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const packageJson = require('../package.json');
+const initCommand     = require('../scripts/init');
+const updateCommand   = require('../scripts/update');
+const doctorCommand   = require('../scripts/doctor');
+const useCommand      = require('../scripts/use');
+const TaskDetector    = require('../scripts/detect');
+const validateCommand = require('../scripts/validate');
+const memoryCommand   = require('../scripts/memory');
+const contextCommand  = require('../scripts/context');
+const promptCommand   = require('../scripts/prompt');
+const removeCommand   = require('../scripts/remove');
+const guideCommand    = require('../scripts/guide');
+const telemetryCommand= require('../scripts/telemetry/cli');
+const taskCommand     = require('../scripts/task');
+const checkpointCommand = require('../scripts/checkpoint');
+const { record }      = require('../scripts/telemetry/record');
+const { updateTaskGateState } = require('../scripts/task');
+
+// ── DEPRECATION WARNING ───────────────────────────────────────
+if (!process.env.AIFLOW_IS_AK) {
+    console.warn(chalk.yellow('\n⚠ Warning: "aiflow" command is deprecated and will be removed in future versions.'));
+    console.warn(chalk.yellow('Please use the shorter "ak" command instead.\n'));
+}
+
+program
+    .version(packageJson.version)
+    .description('AI Flow Kit CLI - AI-powered development workflows for teams');
+
+// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
+// We intercept raw argv here so we can catch --version, --help,
+// and invalid commands *before* Commander exits the process.
+// Also alias `-v` to commander's `-V` at the root only — subcommands still
+// keep `-v` as `--verbose`. And alias `--fw` to `--framework`.
+(() => {
+    if (process.argv[2] === '-v') process.argv[2] = '-V';
+    for (let i = 3; i < process.argv.length; i++) {
+        if (process.argv[i] === '--fw') process.argv[i] = '--framework';
+    }
+    const args = process.argv.slice(2);
+    let cmd = 'help';
+    if (args.length > 0) {
+        let first = args[0];
+
+        // 1. Phân giải alias cho root commands
+        const aliases = {
+            'i': 'init',
+            'u': 'use',
+            'p': 'prompt',
+            'd': 'detect',
+            't': 'task',
+            'ctx': 'context',
+            'cp': 'checkpoint',
+            'vl': 'validate',
+            'mem': 'memory',
+            'g': 'guide',
+            'rm': 'remove',
+            'up': 'update',
+            'sync': 'sync-skills',
+            'dr': 'doctor',
+            'tel': 'telemetry'
+        };
+        if (aliases[first]) {
+            first = aliases[first];
+        }
+
+        if (['-V', '-v', '--version'].includes(first)) {
+            cmd = 'version';
+        } else if (['-h', '--help'].includes(first)) {
+            cmd = 'help';
+        } else if (first.startsWith('-')) {
+            cmd = 'unknown_flag';
+            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
+        } else if (first === 'memory') {
+            const sec = args[1];
+            // Phân giải alias cho memory subcommands
+            let sub = sec;
+            if (sec && !sec.startsWith('-')) {
+                const memAliases = {
+                    's': 'save',
+                    'g': 'get',
+                    'ls': 'list',
+                    'sr': 'search',
+                    'd': 'delete',
+                    'cl': 'clear'
+                };
+                if (memAliases[sec]) sub = memAliases[sec];
+                cmd = `memory.${sub}`;
+            } else {
+                cmd = 'memory';
+            }
+        } else if (first === 'task') {
+            const sec = args[1];
+            // Phân giải alias subcommand của task
+            let sub = sec;
+            if (sec && !sec.startsWith('-')) {
+                const subAliases = {
+                    'st': 'status',
+                    'ls': 'list',
+                    'p': 'pause',
+                    'sw': 'switch',
+                    'r': 'resume',
+                    'rst': 'reset',
+                    'rm': 'remove',
+                    'n': 'next'
+                };
+                if (subAliases[sec]) sub = subAliases[sec];
+                cmd = `task.${sub}`;
+            } else {
+                cmd = 'task';
+            }
+        } else {
+            cmd = first;
+            if (args.includes('--help') || args.includes('-h')) {
+                cmd = `${first}.help`;
+            }
+        }
+    }
+    // Record everything except telemetry and gate actions (gate records its own rich event)
+    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
+        record('command.invoked', { command: cmd });
+    }
+})();
+
+
+// ── init ──────────────────────────────────────────────────────
+program
+    .command('init')
+    .alias('i')
+    .description('Initialize AI Flow Kit in your project')
+    .option('-f, --framework <types>', 'framework(s), comma-separated (e.g. spring-boot,reactjs)')
+    .option('-a, --adapter <types>', 'adapter(s), comma-separated (e.g. backlog,jira)')
+    .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
+    .option('--with-rtk', 'force enable RTK token compression hook')
+    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
+    .action((options) => {
+        options.frameworks = options.framework
+            ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
+            : [];
+        options.adapters = options.adapter
+            ? options.adapter.split(',').map(s => s.trim()).filter(Boolean)
+            : [];
+        options.aiTools = options.env
+            ? options.env.split(',').map(s => s.trim()).filter(Boolean)
+            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
+
+        initCommand(options);
+    });
+
+// ── use ───────────────────────────────────────────────────────
+program
+    .command('use [targets...]')
+    .alias('u')
+    .description('Load context from ticket(s), version, or file(s). First target is primary; rest become supplementary context.')
+    .option('-m, --manual', 'manual context entry')
+    .option('-f, --file <path>', 'load from file')
+    .option('-s, --save <name>', 'save as named context')
+    .option('-c, --coms', 'load all comments (alias for --with-comments)')
+    .option('--with-comments', 'load all comments')
+    .option('--cid <id>', 'load a specific comment by ID')
+    .option('--clast <n>', 'load the last N comments', parseInt)
+    .option('--cfrom <id>', 'load comments from ID N onward', parseInt)
+    .option('--cto <id>', 'load comments up to ID N', parseInt)
+    .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
+    .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
+    .addHelpText('after', `
+Examples:
+  $ ak use PROJ-33                                  Single ticket (primary only)
+  $ ak use PROJ-33 PROJ-10 docs/arch.md             Multi-target: PROJ-33 primary, rest supplementary (v0.1.0+)
+  $ ak use https://company.backlog.com/view/PROJ-33 Load by Backlog URL
+  $ ak use PROJ-33 -c                               Include all comments
+  $ ak use PROJ-33 --clast 5                        Newest 5 comments only
+  $ ak use --file task.md                           Load from local file
+  $ ak use --manual                                 Manual entry
+
+Auto link resolution (v0.1.0+):
+  Backlog/Jira URLs in the primary ticket description are auto-fetched and added
+  to supplementaryContext[]. Comment links (#comment-456 or ?focusedCommentId=456)
+  fetch only that comment. Capped at 5 auto-resolved links per call.
+
+Related:
+  ak fetch-links <url>   Fetch a single Backlog/Jira link → JSON (AI runtime use)
+`)
+    .action((targets, options) => {
+        useCommand(targets, options);
+    });
+
+// ── fetch-links ───────────────────────────────────────────────
+program
+    .command('fetch-links <url>')
+    .description('Fetch a backlog/jira link and output SupplementaryContext JSON to stdout. Used by AI at runtime.')
+    .addHelpText('after', `
+Examples:
+  $ ak fetch-links "https://company.backlog.com/view/PROJ-10"
+  $ ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
+  $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10"
+  $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"
+
+Exit codes:
+  0   Success — JSON written to stdout
+  1   URL not recognised, or fetch failed (error on stderr)
+`)
+    .action(async (url) => {
+        const { fetchLink } = require('../scripts/link-resolver');
+        const { loadCredentials } = require('../scripts/use');
+        const credentials = await loadCredentials();
+        try {
+            const result = await fetchLink(url, credentials);
+            if (!result) {
+                process.stderr.write(`Not a recognized backlog/jira URL: ${url}\n`);
+                process.exit(1);
+            }
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        } catch (err) {
+            process.stderr.write(`Error fetching link: ${err.message}\n`);
+            process.exit(1);
+        }
+    });
+
+// ── prompt ────────────────────────────────────────────────────
+program
+    .command('prompt [type]')
+    .alias('p')
+    .description('Generate AI prompt with context and rules')
+    .option('-l, --list', 'list available prompt types')
+    .option('-o, --output <file>', 'save to file')
+    .option('-L, --lang <lang>', 'language: english (default) or vietnamese')
+    .option('-d, --detail <level>', 'detail level: minimal | standard (default) | comprehensive')
+    .action((type, options) => {
+        promptCommand(type, options);
+    });
+
+// ── detect ────────────────────────────────────────────────────
+program
+    .command('detect [description]')
+    .alias('d')
+    .description('Auto-detect task type from description')
+    .option('-v, --verbose', 'show detection details')
+    .option('-t, --threshold <number>', 'confidence threshold (0-100)')
+    .action((description, options) => {
+        const detector = new TaskDetector();
+        const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
+        const result = detector.detect(description, threshold);
+        console.log(chalk.cyan('\nTask Detection Results:\n'));
+        console.log(detector.formatOutput(result, options.verbose));
+    });
+
+// ── task ─────────────────────────────────────────────────────
+const taskCmd = program.command('task').alias('t').description('Manage multiple tasks — pause, switch, resume');
+
+taskCmd
+    .command('status')
+    .alias('st')
+    .description('Show active task and pending tasks')
+    .action(() => { taskCommand('status'); });
+
+taskCmd
+    .command('list')
+    .alias('ls')
+    .description('List all saved tasks')
+    .action(() => { taskCommand('list'); });
+
+taskCmd
+    .command('pause')
+    .alias('p')
+    .description('Pause current task and save progress')
+    .option('-n, --note <text>', 'note about why you are pausing')
+    .action((opts) => { taskCommand('pause', { note: opts.note }); });
+
+taskCmd
+    .command('switch <ticket-id>')
+    .alias('sw')
+    .description('Pause current task and switch to another')
+    .action((ticketId) => { taskCommand('switch', { taskId: ticketId }); });
+
+taskCmd
+    .command('resume <ticket-id>')
+    .alias('r')
+    .description('Resume a paused task')
+    .action((ticketId) => { taskCommand('resume', { taskId: ticketId }); });
+
+taskCmd
+    .command('reset <ticket-id>')
+    .alias('rst')
+    .description('Reset task to Gate 1 (keeps ticket context, clears gate progress)')
+    .action((ticketId) => { taskCommand('reset', { taskId: ticketId }); });
+
+taskCmd
+    .command('remove <ticket-id>')
+    .alias('rm')
+    .description('Permanently delete all saved data for a task')
+    .action((ticketId) => { taskCommand('remove', { taskId: ticketId }); });
+
+taskCmd
+    .command('next')
+    .alias('n')
+    .description('Approve current gate and prepare next session (saves state for resume)')
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        taskCommand('next', { taskId: opts.ticket });
+    });
+
+// ── context ───────────────────────────────────────────────────
+program
+    .command('context [action]')
+    .alias('ctx')
+    .description('Manage task contexts (list|show|save <name>|clear)')
+    .option('-s, --save <name>', 'save current context with name')
+    .option('-l, --load <name>', 'load saved context by name')
+    .option('-d, --delete <name>', 'delete saved context')
+    .option('--clear', 'clear all saved contexts')
+    .option('--show', 'show current context')
+    .action((action, options) => {
+        contextCommand(action, options);
+    });
+
+// ── checkpoint ────────────────────────────────────────────────
+program
+    .command('checkpoint')
+    .alias('cp')
+    .description('Record token usage checkpoint (called by AI during gate work)')
+    .requiredOption('-g, --gate <n>', 'gate number (1–5)', parseInt)
+    .requiredOption('-s, --step <name>', 'step name (e.g. "tests-written")')
+    .requiredOption('-n, --tokens <n>', 'estimated token count', parseInt)
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
+    });
+
+// ── validate ──────────────────────────────────────────────────
+program
+    .command('validate <file>')
+    .alias('vl')
+    .description('Validate output against team rules')
+    .option('-r, --ruleset <set>', 'rule set: default | strict | lenient', 'default')
+    .option('-v, --verbose', 'detailed report')
+    .option('-x, --fix', 'auto-fix trailing whitespace')
+    .action((file, options) => {
+        validateCommand(file, {
+            ruleset: options.ruleset,
+            verbose: options.verbose,
+            fix: options.fix
+        });
+    });
+
+// ── memory ────────────────────────────────────────────────────
+// Sub-commands to avoid the ambiguous "memory <action> --save key" pattern
+const memCmd = program.command('memory').alias('mem').description('Manage team knowledge and memory');
+
+memCmd
+    .command('save <key> <value>')
+    .alias('s')
+    .description('Save a memory entry')
+    .action((key, value) => { memoryCommand('save', { key, value }); });
+
+memCmd
+    .command('get <key>')
+    .alias('g')
+    .description('Retrieve a memory entry')
+    .action((key) => { memoryCommand('get', { key }); });
+
+memCmd
+    .command('list')
+    .alias('ls')
+    .description('List all memories')
+    .action(() => { memoryCommand('list'); });
+
+memCmd
+    .command('search <query>')
+    .alias('sr')
+    .description('Search memories by keyword')
+    .action((query) => { memoryCommand('search', { query }); });
+
+memCmd
+    .command('delete <key>')
+    .alias('d')
+    .description('Delete a memory entry')
+    .action((key) => { memoryCommand('delete', { key }); });
+
+memCmd
+    .command('clear')
+    .alias('cl')
+    .description('Clear all memories')
+    .action(() => { memoryCommand('clear'); });
+
+// ── guide ─────────────────────────────────────────────────────
+program
+    .command('guide')
+    .alias('g')
+    .description('Show quickstart guide, architecture, and command reference')
+    .option('-f, --flow', 'show architecture & flow diagram only')
+    .option('-c, --commands', 'show command reference only')
+    .action((options) => {
+        guideCommand(options);
+    });
+
+// ── telemetry feedback helper ─────────────────────────────────
+function showTelResult(result, label) {
+    try {
+        if (!result) return;
+        if (result.ok) {
+            console.log(chalk.green(`  [tel] ✓ ${label} logged`));
+        } else if (result.reason === 'disabled') {
+            console.log(chalk.yellow(`  [tel] ⚠ skipped — telemetry is disabled (run 'aiflow telemetry enable')`));
+        } else if (result.reason === 'opted-out') {
+            console.log(chalk.yellow(`  [tel] ⚠ skipped — repo has .aiflow/no-telemetry opt-out`));
+        } else if (result.reason === 'no-url') {
+            console.log(chalk.yellow(`  [tel] ⚠ skipped — no server URL configured (run 'aiflow telemetry enable')`));
+        } else if (result.error) {
+            console.log(chalk.yellow(`  [tel] ⚠ error logging '${label}': ${result.error}`));
+        }
+    } catch (e) { /* never block main flow */ }
+}
+
+// ── gate (telemetry for gate workflow events) ─────────────────
+program
+    .command('gate <number> <action>')
+    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
+    .option('--ticket <id>', 'ticket ID')
+    .option('--ai-tool <tool>', 'AI tool name')
+    .action((number, action, options) => {
+        const gateNum = parseInt(number);
+        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
+        if (!['start', 'approved'].includes(action)) return;
+
+        const ticketId = options.ticket || '';
+
+        const telResult = record(`gate.${action}`, {
+            gate: gateNum,
+            ticket_id: ticketId,
+            command: `gate${gateNum}.${action}`,
+            ai_tool: options.aiTool || ''
+        });
+        showTelResult(telResult, `gate${gateNum}.${action}`);
+
+        // Keep task-state.json currentGate in sync (silent — never blocks the AI)
+        if (ticketId) {
+            updateTaskGateState(ticketId, gateNum, action).catch(() => {});
+        }
+
+        if (action === 'approved') {
+            console.log(chalk.cyan(`\n  Gate ${gateNum} approved!`));
+            console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
+            console.log(chalk.gray(`  Run: aiflow task next${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
+            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
+        }
+    });
+
+// ── remove ────────────────────────────────────────────────────
+program
+    .command('remove')
+    .alias('rm')
+    .description('Remove ai-flow-kit from project, a cached version, or uninstall globally')
+    .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
+    .option('-g, --global', 'uninstall the global npm package (removes `aiflow` command)')
+    .action((options) => {
+        removeCommand(options);
+    });
+
+// ── update ────────────────────────────────────────────────────
+program
+    .command('update')
+    .alias('up')
+    .description('Update to latest version')
+    .option('-f, --force', 'force update even if already on latest')
+    .action((options) => {
+        updateCommand(options);
+    });
+
+// ── sync-skills ───────────────────────────────────────────────
+program
+    .command('sync-skills')
+    .alias('sync')
+    .description('Manually synchronize AI Instruction files with local custom skills')
+    .action(async () => {
+        const projectDir = process.cwd();
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
+        const fs = require('fs-extra');
+        const path = require('path');
+        const chalk = require('chalk');
+
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (!(await fs.pathExists(stateFile))) {
+            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
+            return;
+        }
+
+        const state = await fs.readJson(stateFile);
+        const frameworks = state.frameworks || [];
+        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
+
+        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+        }
+        await ensureAiflowGitignored(projectDir);
+        console.log(chalk.green('✨ Sync completed!'));
+    });
+
+// ── doctor ────────────────────────────────────────────────────
+program
+    .command('doctor')
+    .alias('dr')
+    .description('Health check of AI Flow Kit setup')
+    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
+    .option('-v, --verbose', 'detailed output')
+    .action((opts) => {
+        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
+    });
+
+// ── telemetry ──────────────────────────────────────────────────
+program
+    .command('telemetry [action]')
+    .alias('tel')
+    .description('Manage telemetry logging (enable|disable|status|log)')
+    .option('--event <event>', 'event name (for log action)')
+    .option('--detail <detail>', 'detail string (for log action)')
+    .action((action, options) => {
+        telemetryCommand(action || 'status', options);
+    });
+
+program.parse(process.argv);