@relipa/ai-flow-kit 0.1.1-beta.0 → 0.1.2-beta.0

package/scripts/init.js

@@ -1,1009 +1,1112 @@
-const fs = require('fs-extra');
-const path = require('path');
-const os = require('os');
-const chalk = require('chalk');
-const { input, checkbox, confirm } = require('@inquirer/prompts');
-
-const PKG_DIR = path.join(__dirname, '..');
-const GLOBAL_AIFLOW_DIR = path.join(os.homedir(), '.aiflow');
-const GLOBAL_CREDENTIALS_PATH = path.join(GLOBAL_AIFLOW_DIR, 'credentials.json');
-const PKG_VERSION = require('../package.json').version;
-const { execSync, spawn } = require('child_process');
-
-function commandExists(cmd) {
-    try {
-        const isWin = process.platform === 'win32';
-        const checkCmd = isWin ? `where ${cmd}` : `which ${cmd}`;
-        execSync(checkCmd, { stdio: 'ignore' });
-        return true;
-    } catch (_) {
-        return false;
-    }
-}
-
-// Map framework → language family for picking the right rules
-const FRAMEWORK_LANGUAGE = {
-    'laravel':      'php',
-    'php':          'php',
-    'spring-boot':  'java',
-    'reactjs':      'javascript',
-    'nextjs':       'javascript',
-    'vue-nuxt':     'javascript',
-    'nestjs':       'javascript',
-};
-
-const AI_TOOL_FILES = {
-    'claude':   'CLAUDE.md',
-    'cursor':   '.cursorrules',
-    'gemini':   'GEMINI.md',
-    'copilot':  '.github/copilot-instructions.md',
-    'generic':  '.aiflow/docs/AI_INSTRUCTIONS.md',
-};
-
-/**
- * Copy only docs/common/ to .aiflow/docs in the project.
- * Internal aiflow docs (changelog, architecture…) are never copied out.
- */
-async function copyDocsToProject(projectDir) {
-    const srcCommonDir = path.join(PKG_DIR, 'docs', 'common');
-    if (!(await fs.pathExists(srcCommonDir))) return;
-
-    const destDir = path.join(projectDir, '.aiflow', 'docs');
-    await fs.ensureDir(destDir);
-    await fs.copy(srcCommonDir, destDir, { overwrite: true });
-    console.log(chalk.green(`✓ Documentation copied to .aiflow/docs`));
-}
-
-/**
- * Scan the project directory to guess the framework.
- * Returns a framework key or null if undetected.
- */
-async function detectFramework(projectDir) {
-    // JS / TS — check package.json dependencies
-    const pkgPath = path.join(projectDir, 'package.json');
-    if (await fs.pathExists(pkgPath)) {
-        const pkg = await fs.readJson(pkgPath).catch(() => ({}));
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        if (deps['next'])          return 'nextjs';
-        if (deps['nuxt'])          return 'vue-nuxt';
-        if (deps['vue'])           return 'vue-nuxt';
-        if (deps['@nestjs/core'])  return 'nestjs';
-        if (deps['react'])         return 'reactjs';
-        if (deps['express'] || deps['fastify']) return 'nodejs-express';
-    }
-    // Java — pom.xml / Gradle
-    if (await fs.pathExists(path.join(projectDir, 'pom.xml')))            return 'spring-boot';
-    if (await fs.pathExists(path.join(projectDir, 'build.gradle')))       return 'spring-boot';
-    if (await fs.pathExists(path.join(projectDir, 'build.gradle.kts')))   return 'spring-boot';
-    // PHP — composer.json
-    const composerPath = path.join(projectDir, 'composer.json');
-    if (await fs.pathExists(composerPath)) {
-        const composer = await fs.readJson(composerPath).catch(() => ({}));
-        if ((composer.require || {})['laravel/framework']) return 'laravel';
-        return 'php';
-    }
-    // Python
-    if (await fs.pathExists(path.join(projectDir, 'manage.py'))) return 'python-django';
-    const reqPath = path.join(projectDir, 'requirements.txt');
-    if (await fs.pathExists(reqPath)) {
-        const reqs = (await fs.readFile(reqPath, 'utf-8').catch(() => '')).toLowerCase();
-        if (reqs.includes('fastapi')) return 'python-fastapi';
-        if (reqs.includes('django'))  return 'python-django';
-        return 'python';
-    }
-    if (await fs.pathExists(path.join(projectDir, 'pyproject.toml'))) return 'python';
-    return null;
-}
-
-const FRAMEWORK_CHOICES = [
-    { name: 'Spring Boot (Java)', value: 'spring-boot' },
-    { name: 'React',              value: 'reactjs' },
-    { name: 'Next.js',            value: 'nextjs' },
-    { name: 'Vue / Nuxt',         value: 'vue-nuxt' },
-    { name: 'Laravel (PHP)',      value: 'laravel' },
-    { name: 'PHP',                value: 'php' },
-    { name: 'NestJS',             value: 'nestjs' },
-    { name: 'Node.js / Express',  value: 'nodejs-express' },
-    { name: 'Python',             value: 'python' },
-    { name: 'Python Django',      value: 'python-django' },
-    { name: 'Python FastAPI',     value: 'python-fastapi' },
-];
-
-async function copyAssetsToVersion(versionDir, framework) {
-    // ── Skills: merge upstream + custom ──────────────────────────────
-    const upstreamSkills = path.join(PKG_DIR, 'upstream', 'skills');
-    const customSkills   = path.join(PKG_DIR, 'custom',   'skills');
-
-    await fs.ensureDir(path.join(versionDir, 'skills'));
-    if (await fs.pathExists(upstreamSkills)) {
-        await fs.copy(upstreamSkills, path.join(versionDir, 'skills'), { overwrite: true });
-    }
-    if (await fs.pathExists(customSkills)) {
-        await fs.copy(customSkills, path.join(versionDir, 'skills'), { overwrite: true });
-    }
-
-    // ── Rules: common first, then language-specific override ─────────
-    const rulesTarget    = path.join(versionDir, 'rules');
-    const commonRules    = path.join(PKG_DIR, 'custom', 'rules', 'common');
-    const allRules       = path.join(PKG_DIR, 'custom', 'rules');
-
-    await fs.ensureDir(rulesTarget);
-
-    if (await fs.pathExists(commonRules)) {
-        await fs.copy(commonRules, rulesTarget, { overwrite: true });
-    } else {
-        const entries = await fs.readdir(allRules, { withFileTypes: true });
-        for (const entry of entries) {
-            if (entry.isFile() && entry.name.endsWith('.md')) {
-                await fs.copy(
-                    path.join(allRules, entry.name),
-                    path.join(rulesTarget, entry.name),
-                    { overwrite: true }
-                );
-            }
-        }
-    }
-
-    if (framework) {
-        const lang = FRAMEWORK_LANGUAGE[framework];
-        if (lang) {
-            const langRules = path.join(PKG_DIR, 'custom', 'rules', lang);
-            if (await fs.pathExists(langRules)) {
-                await fs.copy(langRules, rulesTarget, { overwrite: true });
-                console.log(chalk.gray(`  ✓ Applied ${lang} rules`));
-            }
-        }
-    }
-}
-
-async function updateSymlinks(projectDir, versionDir) {
-    const claudeDir = path.join(projectDir, '.claude');
-    await fs.emptyDir(claudeDir);
-    await fs.copy(path.join(versionDir, 'skills'), path.join(claudeDir, 'skills'), { overwrite: true });
-
-    const rulesDir = path.join(projectDir, '.rules');
-    await fs.emptyDir(rulesDir);
-    await fs.copy(path.join(versionDir, 'rules'), rulesDir, { overwrite: true });
-
-    await setupSuperpowersHook(projectDir, claudeDir);
-
-    await fs.writeJson(path.join(projectDir, '.aiflow', 'state.json'), {
-        current_version: PKG_VERSION,
-        framework: null,
-    });
-}
-
-async function setupSuperpowersHook(_projectDir, claudeDir) {
-    const hooksDir = path.join(claudeDir, 'hooks');
-    await fs.ensureDir(hooksDir);
-
-    const hookStartSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
-    const hookStartDest = path.join(hooksDir, 'session-start.js');
-    await fs.copy(hookStartSrc, hookStartDest, { overwrite: true });
-
-    const hookStopSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-stop.js');
-    const hookStopDest = path.join(hooksDir, 'session-stop.js');
-    await fs.copy(hookStopSrc, hookStopDest, { overwrite: true });
-
-    const hookBlockGitSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'block-git-write.js');
-    const hookBlockGitDest = path.join(hooksDir, 'block-git-write.js');
-    await fs.copy(hookBlockGitSrc, hookBlockGitDest, { overwrite: true });
-
-    // Copy telemetry module so hooks can require('../telemetry/record')
-    const telemetrySrc  = path.join(PKG_DIR, 'scripts', 'telemetry');
-    const telemetryDest = path.join(claudeDir, 'telemetry');
-    await fs.copy(telemetrySrc, telemetryDest, { overwrite: true });
-
-    const settingsFile = path.join(claudeDir, 'settings.json');
-    let settings = {};
-    if (await fs.pathExists(settingsFile)) {
-        settings = await fs.readJson(settingsFile).catch(() => ({}));
-    }
-
-    if (!settings.hooks) settings.hooks = {};
-    if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
-    if (!settings.hooks.SessionEnd) settings.hooks.SessionEnd = [];
-    if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
-
-    // Remove legacy SessionStop entries if present
-    if (settings.hooks.SessionStop) delete settings.hooks.SessionStop;
-
-    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
-        h => !(h._aiflowKit)
-    );
-    settings.hooks.SessionStart.push({
-        _aiflowKit: true,
-        hooks: [
-            {
-                type: 'command',
-                command: `node "${hookStartDest.replace(/\\/g, '/')}"`,
-            }
-        ]
-    });
-
-    settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(
-        h => !(h._aiflowKit)
-    );
-    settings.hooks.SessionEnd.push({
-        _aiflowKit: true,
-        hooks: [
-            {
-                type: 'command',
-                command: `node "${hookStopDest.replace(/\\/g, '/')}"`,
-            }
-        ]
-    });
-
-    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
-        h => !(h._aiflowKitBlockGitWrite)
-    );
-    settings.hooks.PreToolUse.push({
-        _aiflowKitBlockGitWrite: true,
-        matcher: 'Bash',
-        hooks: [
-            {
-                type: 'command',
-                command: `node "${hookBlockGitDest.replace(/\\/g, '/')}"`,
-            }
-        ]
-    });
-
-    await fs.writeJson(settingsFile, settings, { spaces: 2 });
-    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionEnd, PreToolUse:block-git-write) configured`));
-}
-
-async function verifySuperpowersSkills(versionDir) {
-    const usingSuperpowers = path.join(versionDir, 'skills', 'using-superpowers', 'SKILL.md');
-    if (await fs.pathExists(usingSuperpowers)) {
-        console.log(chalk.green(`✓ Superpowers skills ready (built-in)`));
-    } else {
-        console.log(chalk.yellow(`! Superpowers skills missing — upstream folder may be empty`));
-    }
-}
-
-async function generateSkillRegistry(projectDir) {
-    const versionDir = path.join(projectDir, '.aiflow', 'versions', PKG_VERSION);
-    const skillsDir  = path.join(versionDir, 'skills');
-    
-    if (!(await fs.pathExists(skillsDir))) return '';
-
-    let registry = `## AI Skill Registry (Superpowers)\n\n`;
-    registry += `I have access to specialized development skills. When a workflow step mentions a skill, read its \`SKILL.md\` file at the path below and follow its instructions exactly.\n\n`;
-    registry += `| Skill | Description | Instruction Path |\n`;
-    registry += `|-------|-------------|------------------|\n`;
-
-    const skillFolders = await fs.readdir(skillsDir);
-    for (const folder of skillFolders) {
-        const skillFile = path.join(skillsDir, folder, 'SKILL.md');
-        if (await fs.pathExists(skillFile)) {
-            const content = await fs.readFile(skillFile, 'utf-8');
-            let description = '';
-            
-            // Extract description from frontmatter or first paragraph
-            const descMatch = content.match(/description:\s*(.*)/i);
-            if (descMatch) {
-                description = descMatch[1].trim();
-            } else {
-                const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('---'));
-                description = lines[0] ? lines[0].trim() : 'No description available';
-            }
-
-            // Path relative to project root
-            const relPath = path.relative(projectDir, skillFile).replace(/\\/g, '/');
-            registry += `| **${folder}** | ${description} | \`${relPath}\` |\n`;
-        }
-    }
-    registry += `\n`;
-    return registry;
-}
-
-async function setupFramework(projectDir, framework, multi = false, selectedTools = Object.keys(AI_TOOL_FILES)) {
-    if (!framework) return;
-    const frameworkTemplatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
-    if (!(await fs.pathExists(frameworkTemplatePath))) {
-        console.log(chalk.yellow(`! No template found for framework: ${framework}`));
-        return;
-    }
-
-    const frameworkContent = await fs.readFile(frameworkTemplatePath, 'utf-8');
-    const workflowPath = path.join(PKG_DIR, 'custom', 'templates', 'shared', 'gate-workflow.md');
-    const workflowContent = (await fs.pathExists(workflowPath))
-        ? await fs.readFile(workflowPath, 'utf-8')
-        : '';
-
-    const separator = `\n\n---\n\n`;
-    const skillRegistry = await generateSkillRegistry(projectDir);
-
-    const written = [];
-    const skipped = [];
-
-    for (const tool of selectedTools) {
-        const targetPath = path.join(projectDir, AI_TOOL_FILES[tool]);
-        if (!targetPath) continue;
-
-        await fs.ensureDir(path.dirname(targetPath));
-
-        let finalContent = '';
-
-        const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
-        if (await fs.pathExists(toolTemplatePath)) {
-            finalContent += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
-        }
-
-        if (skillRegistry) {
-            finalContent += skillRegistry + '\n\n';
-        }
-
-        if (workflowContent) {
-            finalContent += workflowContent + '\n\n';
-        }
-
-        const markerStart = '<!-- aiflow-kit-start -->';
-        const markerEnd   = '<!-- aiflow-kit-end -->';
-        
-        finalContent = `${markerStart}\n${finalContent.trim()}\n${markerEnd}`;
-
-        const fileExists = await fs.pathExists(targetPath);
-
-        if (!multi) {
-            const relPath = path.relative(projectDir, targetPath).replace(/\\/g, '/');
-            if (fileExists) {
-                const existingContent = await fs.readFile(targetPath, 'utf-8');
-                const hasStart = existingContent.includes(markerStart);
-                const hasEnd = existingContent.includes(markerEnd);
-
-                if (hasStart && hasEnd) {
-                    const doUpdate = await confirm({ 
-                        message: `File ${relPath} already contains an AI Flow block. Do you want to update this block? (Your custom rules will not be affected)`,
-                        default: true
-                    });
-                    if (doUpdate) {
-                        const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`, 'g');
-                        const updatedContent = existingContent.replace(regex, finalContent);
-                        await fs.writeFile(targetPath, updatedContent);
-                        console.log(chalk.green(`  ✓ Updated AI Flow block in ${relPath}`));
-                        written.push(AI_TOOL_FILES[tool]);
-                    } else {
-                        const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
-                        await fs.ensureDir(path.dirname(refPath));
-                        await fs.writeFile(refPath, finalContent);
-                        const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
-                        console.log(chalk.gray(`  ✓ Skipped ${relPath} — aiflow template saved to ${refRel}`));
-                        skipped.push(relPath);
-                    }
-                } else {
-                    const doOverwrite = await confirm({ 
-                        message: `File ${relPath} is missing the new AI Flow marker block. Do you want to OVERWRITE it completely with the latest template?`,
-                        default: true
-                    });
-                    if (doOverwrite) {
-                        await fs.writeFile(targetPath, finalContent);
-                        console.log(chalk.green(`  ✓ Overwrote ${relPath} with latest AI Flow template`));
-                        written.push(AI_TOOL_FILES[tool]);
-                    } else {
-                        const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
-                        await fs.ensureDir(path.dirname(refPath));
-                        await fs.writeFile(refPath, finalContent);
-                        const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
-                        console.log(chalk.gray(`  ✓ Skipped ${relPath} — aiflow template saved to ${refRel}`));
-                        skipped.push(relPath);
-                    }
-                }
-            } else {
-                const doCreate = await confirm({ 
-                    message: `File ${relPath} does not exist. Do you want to create it using the latest AI Flow template?`,
-                    default: true
-                });
-                if (doCreate) {
-                    await fs.writeFile(targetPath, finalContent);
-                    written.push(AI_TOOL_FILES[tool]);
-                }
-            }
-        } else {
-            if (fileExists) {
-                await fs.appendFile(targetPath, separator + frameworkContent);
-            } else {
-                await fs.writeFile(targetPath, finalContent);
-            }
-            written.push(AI_TOOL_FILES[tool]);
-        }
-    }
-
-    if (written.length) {
-        console.log(chalk.green(`✓ AI instruction files updated for framework: ${framework} (${written.join(', ')})`));
-    }
-    if (skipped.length) {
-        console.log(chalk.yellow(`  Skipped (kept existing): ${skipped.join(', ')}`));
-    }
-}
-
-async function setupAdapter(projectDir, adapter) {
-    if (!adapter) return;
-    const presetPath = path.join(PKG_DIR, 'custom', 'mcp-presets', `${adapter}.json`);
-    if (!(await fs.pathExists(presetPath))) {
-        console.log(chalk.yellow(`! No MCP preset found for adapter: ${adapter}`));
-        return;
-    }
-
-    const { mcpServers } = await fs.readJson(presetPath);
-    const serverKey    = Object.keys(mcpServers)[0];
-    const serverConfig = mcpServers[serverKey];
-
-    let existingCreds = {};
-    if (await fs.pathExists(GLOBAL_CREDENTIALS_PATH)) {
-        const globalData = await fs.readJson(GLOBAL_CREDENTIALS_PATH).catch(() => ({}));
-        existingCreds = globalData.mcp || {};
-    }
-
-    console.log(chalk.cyan(`\nSetup MCP adapter for ${adapter}:`));
-    console.log(chalk.gray('Press Enter to keep existing value shown in [brackets]\n'));
-
-    const credentials = {};
-    for (const [envKey] of Object.entries(serverConfig.env)) {
-        const current = existingCreds[envKey];
-        const hint = current
-            ? `[${maskSecret(current)}]`
-            : chalk.gray('[not set — required]');
-
-        let resolved = '';
-        while (true) {
-            const value = await input({
-                message: `${envKey} ${hint}:`,
-                default: '',
-            });
-            resolved = value.trim() || current || '';
-            if (resolved) break;
-            console.log(chalk.red(`  ✗ ${envKey} is required. Please enter a value.`));
-        }
-        serverConfig.env[envKey] = resolved;
-        credentials[envKey] = resolved;
-    }
-
-    console.log(chalk.cyan(`\nVerifying ${adapter} credentials...`));
-    const verifyResult = await verifyAdapterCredentials(adapter, credentials);
-    if (!verifyResult.ok) {
-        console.log(chalk.red(`✗ Verification failed: ${verifyResult.error}`));
-        console.log(chalk.yellow('  Credentials saved but may not work. Re-run `aiflow init --adapter ' + adapter + '` to update.'));
-    } else {
-        console.log(chalk.green(`✓ Credentials verified successfully`));
-    }
-
-    const claudeConfigDir = path.join(
-        process.env.APPDATA ||
-        (process.platform === 'darwin'
-            ? process.env.HOME + '/Library/Application Support'
-            : process.env.HOME + '/.config'),
-        'Claude'
-    );
-    const mcpConfigFile = path.join(claudeConfigDir, 'claude_desktop_config.json');
-    let existingConfig = { mcpServers: {} };
-    if (await fs.pathExists(mcpConfigFile)) {
-        existingConfig = await fs.readJson(mcpConfigFile).catch(() => ({ mcpServers: {} }));
-    }
-    if (!existingConfig.mcpServers) existingConfig.mcpServers = {};
-    existingConfig.mcpServers[serverKey] = serverConfig;
-    await fs.ensureDir(path.dirname(mcpConfigFile));
-    await fs.writeJson(mcpConfigFile, existingConfig, { spaces: 2 });
-
-    await fs.writeJson(
-        path.join(projectDir, '.mcp.json'),
-        { mcpServers: { [serverKey]: serverConfig } },
-        { spaces: 2 }
-    );
-
-    await fs.ensureDir(GLOBAL_AIFLOW_DIR);
-    let globalData = {};
-    if (await fs.pathExists(GLOBAL_CREDENTIALS_PATH)) {
-        globalData = await fs.readJson(GLOBAL_CREDENTIALS_PATH).catch(() => ({}));
-    }
-    globalData.mcp = { ...(globalData.mcp || {}), ...credentials };
-    await fs.writeJson(GLOBAL_CREDENTIALS_PATH, globalData, { spaces: 2 });
-    await ensureAiflowGitignored(projectDir);
-
-    console.log(chalk.green(`✓ MCP configuration saved (global + local + credentials).`));
-}
-
-async function verifyAdapterCredentials(adapter, credentials) {
-    try {
-        if (adapter === 'backlog') return await verifyBacklog(credentials);
-        if (adapter === 'jira') return await verifyJira(credentials);
-        if (adapter === 'figma') return await verifyFigma(credentials);
-        return { ok: true };
-    } catch (err) {
-        return { ok: false, error: err.message };
-    }
-}
-
-function verifyBacklog(credentials) {
-    const https = require('https');
-    const apiKey   = credentials.BACKLOG_API_KEY;
-    const spaceKey = credentials.BACKLOG_SPACE_KEY;
-    const domain   = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
-
-    return new Promise((resolve) => {
-        const url = `https://${domain}/api/v2/users/myself?apiKey=${apiKey}`;
-        const req = https.get(url, (res) => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => {
-                if (res.statusCode === 200) {
-                    const user = JSON.parse(data);
-                    resolve({ ok: true, user: user.name });
-                } else if (res.statusCode === 401) {
-                    resolve({ ok: false, error: 'Invalid API key' });
-                } else if (res.statusCode === 404) {
-                    resolve({ ok: false, error: `Space "${spaceKey}" not found` });
-                } else {
-                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
-                }
-            });
-        });
-        req.on('error', (err) => resolve({ ok: false, error: err.message }));
-        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
-    });
-}
-
-function verifyJira(credentials) {
-    const https = require('https');
-    const { JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN } = credentials;
-    const auth = Buffer.from(`${JIRA_EMAIL}:${JIRA_API_TOKEN}`).toString('base64');
-
-    return new Promise((resolve) => {
-        const options = {
-            hostname: `${JIRA_DOMAIN}.atlassian.net`,
-            path: '/rest/api/3/myself',
-            headers: { 'Authorization': `Basic ${auth}`, 'Accept': 'application/json' },
-        };
-        const req = https.get(options, (res) => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => {
-                if (res.statusCode === 200) {
-                    resolve({ ok: true });
-                } else if (res.statusCode === 401) {
-                    resolve({ ok: false, error: 'Invalid email or API token' });
-                } else {
-                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
-                }
-            });
-        });
-        req.on('error', (err) => resolve({ ok: false, error: err.message }));
-        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
-    });
-}
-
-function verifyFigma(credentials) {
-    const https = require('https');
-    const { FIGMA_API_TOKEN } = credentials;
-
-    return new Promise((resolve) => {
-        const options = {
-            hostname: 'api.figma.com',
-            path: '/v1/me',
-            headers: { 'X-Figma-Token': FIGMA_API_TOKEN },
-        };
-        const req = https.get(options, (res) => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => {
-                if (res.statusCode === 200) {
-                    const user = JSON.parse(data);
-                    resolve({ ok: true, user: user.name || user.email });
-                } else if (res.statusCode === 403 || res.statusCode === 401) {
-                    resolve({ ok: false, error: 'Invalid Figma API token' });
-                } else {
-                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
-                }
-            });
-        });
-        req.on('error', (err) => resolve({ ok: false, error: err.message }));
-        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
-    });
-}
-
-async function ensureAiflowGitignored(projectDir) {
-    const gitignorePath = path.join(projectDir, '.gitignore');
-    const entries = [
-        '.aiflow/',
-        'plan/',
-        '.claude/',
-        '.rules/',
-        '.mcp.json',
-        'CLAUDE.md',
-        'GEMINI.md',
-        '.cursorrules',
-        '.github/copilot-instructions.md'
-    ];
-    let content = '';
-    if (await fs.pathExists(gitignorePath)) {
-        content = await fs.readFile(gitignorePath, 'utf-8');
-    }
-    const lines = content.split('\n').map(l => l.trim());
-    let changed = false;
-    let separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
-
-    for (const entry of entries) {
-        if (!lines.includes(entry)) {
-            content += `${separator}${entry}\n`;
-            separator = '';
-            changed = true;
-            console.log(chalk.yellow(`  ⚠ Added ${entry} to .gitignore`));
-        }
-    }
-    if (changed) {
-        await fs.writeFile(gitignorePath, content);
-    }
-}
-
-function maskSecret(value) {
-    if (!value || value.length <= 8) return '***';
-    return `${value.slice(0, 4)}***${value.slice(-4)}`;
-}
-
-// ── GitNexus (code intelligence) helpers ─────────────────────────
-
-const IGNORE_DIRS = new Set([
-    '.git', 'node_modules', 'target', 'build', '.aiflow',
-    'dist', 'out', '.next', '.nuxt', 'vendor', 'coverage', '.gradle',
-]);
-const SOURCE_EXT = /\.(java|kt|groovy|js|ts|jsx|tsx|mjs|cjs|php|py|go|rb|cs|cpp|c|h|rs|vue|svelte|xml|yml|yaml|sql|properties)$/i;
-async function countSourceFiles(dir) {
-    let count = 0;
-    const scan = async (d) => {
-        let entries;
-        try { entries = await fs.readdir(d, { withFileTypes: true }); } catch (_) { return; }
-        for (const e of entries) {
-            if (e.isDirectory()) {
-                if (!IGNORE_DIRS.has(e.name) && !e.name.startsWith('.')) await scan(path.join(d, e.name));
-            } else if (SOURCE_EXT.test(e.name)) {
-                count++;
-            }
-        }
-    };
-    await scan(dir);
-    return count;
-}
-
-async function isGitNexusConfigured(projectDir) {
-    const mcpPath = path.join(projectDir, '.mcp.json');
-    if (!(await fs.pathExists(mcpPath))) return false;
-    const mcp = await fs.readJson(mcpPath).catch(() => ({}));
-    return !!(mcp.mcpServers && mcp.mcpServers.gitnexus);
-}
-
-async function setupGitNexus(projectDir, wait = false) {
-    const { spawn } = require('child_process');
-    // On Windows, use shell:true so npm scripts (.cmd) resolve correctly — avoids EINVAL
-    const isWin   = process.platform === 'win32';
-    const npxCmd  = 'npx';
-    const spawnOpts = (extra = {}) => ({ shell: isWin, windowsHide: true, ...extra });
-
-    // 1. Inject MCP server config into .mcp.json (merge, don't overwrite)
-    const mcpPath = path.join(projectDir, '.mcp.json');
-    let existing = {};
-    if (await fs.pathExists(mcpPath)) {
-        existing = await fs.readJson(mcpPath).catch(() => ({}));
-    }
-    if (!existing.mcpServers) existing.mcpServers = {};
-    const mcpAlreadyPresent = !!(existing.mcpServers.gitnexus);
-    
-    // 3. Detect if gitnexus is already available in PATH (preferred over npx)
-    const hasGlobalGitNexus = commandExists('gitnexus');
-    if (hasGlobalGitNexus) {
-        existing.mcpServers.gitnexus = { command: 'gitnexus', args: ['mcp'] };
-        console.log(chalk.gray('  ✓ Global gitnexus found — using it for MCP and indexing.'));
-    } else {
-        existing.mcpServers.gitnexus = { command: 'npx', args: ['-y', 'gitnexus@latest', 'mcp'] };
-    }
-    await fs.writeJson(mcpPath, existing, { spaces: 2 });
-    if (!mcpAlreadyPresent) {
-        console.log(chalk.green('✓ GitNexus MCP server configured (.mcp.json)'));
-    }
-
-    const nodeMajor = parseInt(process.version.slice(1).split('.')[0], 10);
-    if (nodeMajor < 20) {
-        console.log(chalk.yellow(`⚠ GitNexus indexing skipped — requires Node.js >=20.0.0 (current: ${process.version}).`));
-        console.log(chalk.gray('  MCP config saved. After upgrading Node.js, run: npx gitnexus analyze'));
-        return;
-    }
-
-    const aiflowDir = path.join(projectDir, '.aiflow');
-    await fs.ensureDir(aiflowDir);
-    const statusPath  = path.join(aiflowDir, 'gitnexus-status.json');
-    const startedAt   = new Date().toISOString();
-    await fs.writeJson(statusPath, { status: 'running', startedAt });
-
-    if (!wait) {
-        const workerPath = path.join(__dirname, 'gitnexus-worker.js');
-        const child = spawn(process.execPath, [workerPath, projectDir],
-            spawnOpts({ detached: true, stdio: 'ignore' }));
-        child.unref();
-        console.log(chalk.cyan('⟳ GitNexus: indexing codebase in background...'));
-        console.log(chalk.gray('  Notification will appear when you run `aiflow use <TICKET>` next time.'));
-        return;
-    }
-
-    const fileCount = await countSourceFiles(projectDir);
-    console.log(chalk.cyan(`⟳ GitNexus: indexing ${fileCount} source files (this may take 10–30 min on first run)...`));
-    console.log(chalk.gray('  Remove --wait to index in background instead.'));
-
-    await new Promise((resolve) => {
-        const runIndexing = (withMoreRam = false) => {
-            const currentCmd = hasGlobalGitNexus ? 'gitnexus' : 'npx';
-            const currentArgs = hasGlobalGitNexus ? ['analyze'] : ['-y', 'gitnexus@latest', 'analyze'];
-            const env = { ...process.env };
-            if (withMoreRam) {
-                const ramSize = withMoreRam === '8g' ? '8192' : '4096';
-                env.NODE_OPTIONS = `--max-old-space-size=${ramSize}`;
-            }
-
-            const child = spawn(currentCmd, currentArgs,
-                spawnOpts({ cwd: projectDir, stdio: ['ignore', 'inherit', 'inherit'], env }));
-
-            child.on('close', async (code) => {
-                const completedAt = new Date().toISOString();
-                if (code === 0) {
-                    await fs.writeJson(statusPath, { status: 'done', startedAt, completedAt, notified: true });
-                    console.log(chalk.green(`✓ GitNexus: indexed ${fileCount} files — code intelligence is ready.`));
-                    resolve();
-                } else {
-                    console.log(chalk.red(`✗ GitNexus: indexing failed (exit ${code}).`));
-
-                    // Detection of Segmentation Fault / Crash (139 on Linux/Mac, 3221225477 on Windows)
-                    const isCrash = (code === 139 || code === 3221225477);
-                    if (isCrash) {
-                        console.log(chalk.yellow(`\n⚠ Indexing crashed (Segmentation Fault) at ${withMoreRam ? (withMoreRam === '8g' ? '8GB' : '4GB') : 'default'} RAM.`));
-                        
-                        const nextRam = !withMoreRam ? '4g' : (withMoreRam === '4g' ? '8g' : null);
-                        if (nextRam) {
-                            const retry = await confirm({ 
-                                message: `Would you like to retry indexing with increased memory (${nextRam.toUpperCase()})?`, 
-                                default: true 
-                            });
-                            if (retry) {
-                                return runIndexing(nextRam); // Recursion, don't resolve yet
-                            }
-                        } else {
-                            console.log(chalk.red('⚠ Already tried with 8GB RAM. Please check if there are any extremely large files or corrupted database.'));
-                            console.log(chalk.gray('  Try: rm -rf .aiflow/ladybug.db (if exists) or check your .gitignore'));
-                        }
-                    }
-
-                    // If npx failed and gitnexus isn't global, offer to install it global (only if not a crash or if retry was rejected)
-                    if (!hasGlobalGitNexus && !isCrash) {
-                        console.log(chalk.yellow('\nTip: npx failed. Installing gitnexus globally often fixes environment issues.'));
-                        const install = await confirm({ message: 'Would you like me to try installing gitnexus globally for you?', default: true });
-                        if (install) {
-                            try {
-                                console.log(chalk.blue('Running: npm install -g gitnexus ...'));
-                                execSync('npm install -g gitnexus', { stdio: 'inherit' });
-                                console.log(chalk.green('✓ GitNexus installed globally. Please run `aiflow init` again to retry indexing.'));
-                            } catch (err) {
-                                console.log(chalk.red('Failed to install globally. Please try manually: npm install -g gitnexus'));
-                            }
-                        }
-                    }
-
-                    await fs.writeJson(statusPath, { status: 'error', startedAt, completedAt, exitCode: code, notified: true });
-                    resolve();
-                }
-            });
-
-            child.on('error', async (err) => {
-                await fs.writeJson(statusPath, {
-                    status: 'error', startedAt, completedAt: new Date().toISOString(),
-                    exitCode: null, error: err.message, notified: true,
-                });
-                console.log(chalk.red(`✗ GitNexus: failed to start — ${err.message}`));
-                resolve();
-            });
-        };
-
-        runIndexing();
-    });
-}
-
-async function maybeSetupGitNexus(projectDir, withGitNexus, wait = false) {
-    if (!withGitNexus) return;
-
-    // Check if indexing has already completed successfully (not stale)
-    const STALE_MS   = 3 * 60 * 60 * 1000;
-    const statusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
-    let indexDone = false;
-    try {
-        const gn  = await fs.readJson(statusPath);
-        const age = gn.startedAt ? Date.now() - new Date(gn.startedAt).getTime() : Infinity;
-        const staleRunning = gn.status === 'running' && age > STALE_MS;
-        indexDone = gn.status === 'done' && !staleRunning;
-    } catch (_) {}
-
-    if ((await isGitNexusConfigured(projectDir)) && indexDone) {
-        console.log(chalk.gray('  GitNexus already configured and indexed — skipping.'));
-        return;
-    }
-    await setupGitNexus(projectDir, wait);
-}
-
-// ── RTK (token compression) helpers ──────────────────────────────
-
-async function detectRtk() {
-    const { execSync } = require('child_process');
-    try {
-        const out = execSync('rtk --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-        return { installed: true, version: out.replace(/^rtk\s*/i, '') };
-    } catch (_) {
-        return { installed: false };
-    }
-}
-
-async function isRtkHookConfigured(projectDir) {
-    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
-    if (!(await fs.pathExists(settingsPath))) return false;
-    const settings = await fs.readJson(settingsPath).catch(() => ({}));
-    const preHooks = settings?.hooks?.PreToolUse || [];
-    return preHooks.some(h =>
-        (h.hooks || []).some(entry =>
-            typeof entry.command === 'string' && entry.command.includes('rtk')
-        )
-    );
-}
-
-async function setupRtkHook(projectDir) {
-    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
-    let settings = {};
-    if (await fs.pathExists(settingsPath)) {
-        settings = await fs.readJson(settingsPath).catch(() => ({}));
-    }
-    if (!settings.hooks) settings.hooks = {};
-    if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
-
-    const alreadySet = settings.hooks.PreToolUse.some(h =>
-        (h.hooks || []).some(e => typeof e.command === 'string' && e.command.includes('rtk'))
-    );
-    if (alreadySet) return;
-
-    settings.hooks.PreToolUse.push({
-        matcher: 'Bash',
-        hooks: [{ type: 'command', command: 'rtk rewrite' }],
-    });
-    await fs.ensureDir(path.join(projectDir, '.claude'));
-    await fs.writeJson(settingsPath, settings, { spaces: 2 });
-    console.log(chalk.green('✓ RTK token compression hook configured (.claude/settings.json)'));
-}
-
-async function maybeSetupRtk(projectDir, forceSetup) {
-    const rtk = await detectRtk();
-    if (!rtk.installed && !forceSetup) return;
-
-    if (forceSetup && !rtk.installed) {
-        console.log(chalk.yellow('⚠ --with-rtk specified but rtk binary not found. Install: cargo install rtk'));
-        return;
-    }
-
-    if (await isRtkHookConfigured(projectDir)) {
-        console.log(chalk.gray('  RTK hook already configured — skipping.'));
-        return;
-    }
-
-    const enable = forceSetup || await confirm({
-        message: `RTK detected (${rtk.version}). Enable token compression for Claude Code?`,
-        default: true,
-    });
-    if (enable) await setupRtkHook(projectDir);
-}
-
-async function init(options) {
-    const projectDir = process.cwd();
-    const aiflowDir  = path.join(projectDir, '.aiflow');
-    let frameworks = options.frameworks || (options.framework ? [options.framework] : []);
-    const adapters = options.adapters   || (options.adapter   ? [options.adapter]   : []);
-
-    try {
-        console.log(chalk.blue(`Initializing ai-flow-kit (v${PKG_VERSION})...`));
-
-        // ── Auto-detect or prompt for framework if not supplied ──────
-        if (frameworks.length === 0) {
-            const stateFilePath = path.join(aiflowDir, 'state.json');
-            let previousFrameworks = [];
-            if (await fs.pathExists(stateFilePath)) {
-                const savedState = await fs.readJson(stateFilePath);
-                previousFrameworks = savedState.frameworks || [];
-            }
-
-            const detected = await detectFramework(projectDir);
-            const hint = chalk.gray('  Space to select/unselect · Enter to confirm · Leave empty to skip');
-            if (previousFrameworks.length > 0) {
-                const labels = previousFrameworks
-                    .map(v => FRAMEWORK_CHOICES.find(c => c.value === v)?.name || v)
-                    .join(', ');
-                console.log(chalk.cyan(`\n  Previously selected: ${chalk.bold(labels)}`));
-                console.log(hint);
-            } else if (detected) {
-                const label = FRAMEWORK_CHOICES.find(c => c.value === detected)?.name || detected;
-                console.log(chalk.cyan(`\n  Detected framework: ${chalk.bold(label)}`));
-                console.log(hint);
-            } else {
-                console.log(chalk.gray('\n  No framework detected.'));
-                console.log(hint);
-            }
-            const chosen = await checkbox({
-                message: 'Select framework(s):',
-                choices: FRAMEWORK_CHOICES.map(c => ({
-                    ...c,
-                    checked: previousFrameworks.length > 0
-                        ? previousFrameworks.includes(c.value)
-                        : c.value === detected,
-                })),
-            });
-            frameworks = chosen;
-        }
-
-        const primaryFramework = frameworks[0] || null;
-        const versionDir = path.join(aiflowDir, 'versions', PKG_VERSION);
-
-        if (frameworks.length) console.log(chalk.gray(`  Frameworks: ${frameworks.join(', ')}`));
-        if (adapters.length)   console.log(chalk.gray(`  Adapters:   ${adapters.join(', ')}`));
-
-        await fs.ensureDir(versionDir);
-        await copyAssetsToVersion(versionDir, primaryFramework);
-        await verifySuperpowersSkills(versionDir);
-        await updateSymlinks(projectDir, versionDir);
-        await copyDocsToProject(projectDir);
-
-        const selectedTools = options.aiTools || Object.keys(AI_TOOL_FILES);
-        for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
-        }
-        for (const adapter of adapters) {
-            await setupAdapter(projectDir, adapter);
-        }
-
-        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
-        if (await fs.pathExists(stateFile)) {
-            const state = await fs.readJson(stateFile);
-            state.frameworks = frameworks;
-            state.adapters   = adapters;
-            state.aiTools    = selectedTools;
-            await fs.writeJson(stateFile, state);
-        }
-
-        // ── Optional: RTK token compression ─────────────────────────
-        // Commander sets options.rtk=false when --no-rtk is passed
-        if (options.rtk !== false) {
-            await maybeSetupRtk(projectDir, options.withRtk || false);
-        }
-
-        // ── Optional: GitNexus code intelligence ─────────────────────
-        await maybeSetupGitNexus(projectDir, options.withGitnexus || false, options.wait || false);
-
-        // ── Ensure all aiflow files are gitignored ───────────────────
-        await ensureAiflowGitignored(projectDir);
-
-        console.log(chalk.green('\n✨ Initialized AI Flow Kit successfully!'));
-        console.log(chalk.blue('\n' + '─'.repeat(62)));
-        console.log(chalk.bold.white('  Next steps:'));
-
-        if (adapters.length > 0) {
-            console.log(`  ${chalk.green('aiflow use PROJ-33')}    ${chalk.gray('← load ticket from ' + adapters.join('/'))} `);
-        } else {
-            console.log(`  ${chalk.green('aiflow use --manual')}   ${chalk.gray('← input ticket content in terminal')}`);
-            console.log(`  ${chalk.green('aiflow use --file req.md')} ${chalk.gray('← load from local file')}`);
-        }
-
-        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← Claude Code CLI (recommended)')}`);
-        console.log(`  ${chalk.green('Cursor / Gemini')}       ${chalk.gray('← Instructions in .cursorrules / GEMINI.md')}`);
-        console.log(chalk.blue('─'.repeat(62)));
-        console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Commands: ${chalk.green('aiflow guide --commands')}`));
-        console.log(chalk.blue('─'.repeat(62)) + '\n');
-    } catch (err) {
-        console.error(chalk.red(`Error during initialization: ${err.message}`));
-    }
-}
-
-module.exports = init;
-module.exports.AI_TOOL_FILES = AI_TOOL_FILES;
-module.exports.detectRtk = detectRtk;
-module.exports.isRtkHookConfigured = isRtkHookConfigured;
-module.exports.isGitNexusConfigured = isGitNexusConfigured;
-module.exports.setupFramework = setupFramework;
-module.exports.ensureAiflowGitignored = ensureAiflowGitignored;
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const chalk = require('chalk');
+const { input, checkbox, confirm } = require('@inquirer/prompts');
+
+const PKG_DIR = path.join(__dirname, '..');
+const GLOBAL_AIFLOW_DIR = path.join(os.homedir(), '.aiflow');
+const GLOBAL_CREDENTIALS_PATH = path.join(GLOBAL_AIFLOW_DIR, 'credentials.json');
+const PKG_VERSION = require('../package.json').version;
+const { execSync, spawn } = require('child_process');
+
+function commandExists(cmd) {
+    try {
+        const isWin = process.platform === 'win32';
+        const checkCmd = isWin ? `where ${cmd}` : `which ${cmd}`;
+        execSync(checkCmd, { stdio: 'ignore' });
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
+
+// Map framework → language family for picking the right rules
+const FRAMEWORK_LANGUAGE = {
+    'laravel':      'php',
+    'php':          'php',
+    'spring-boot':  'java',
+    'reactjs':      'javascript',
+    'nextjs':       'javascript',
+    'vue-nuxt':     'javascript',
+    'nestjs':       'javascript',
+    'python-ml':    'python',
+};
+
+// Frameworks that use the ML-specific gate workflow instead of the default one
+const ML_FRAMEWORKS = new Set(['python-ml']);
+
+/**
+ * Pick the shared workflow file for a framework.
+ * ML frameworks get ml-gate-workflow.md; everything else keeps gate-workflow.md.
+ */
+function resolveWorkflowFile(framework) {
+    return ML_FRAMEWORKS.has(framework) ? 'ml-gate-workflow.md' : 'gate-workflow.md';
+}
+
+const ML_DEP_PATTERN = /\b(torch|scikit-learn|sklearn|tensorflow|keras|mlflow|wandb)\b/i;
+
+/** Return true if a requirements/pyproject text declares an ML dependency. */
+function detectMlFromDeps(depsText) {
+    return ML_DEP_PATTERN.test(depsText || '');
+}
+
+const AI_TOOL_FILES = {
+    'claude':   'CLAUDE.md',
+    'cursor':   '.cursorrules',
+    'gemini':   'GEMINI.md',
+    'copilot':  '.github/copilot-instructions.md',
+    'generic':  '.aiflow/docs/AI_INSTRUCTIONS.md',
+};
+
+/**
+ * Copy only docs/common/ to .aiflow/docs in the project.
+ * Internal aiflow docs (changelog, architecture…) are never copied out.
+ */
+async function copyDocsToProject(projectDir) {
+    const srcCommonDir = path.join(PKG_DIR, 'docs', 'common');
+    if (!(await fs.pathExists(srcCommonDir))) return;
+
+    const destDir = path.join(projectDir, '.aiflow', 'docs');
+    await fs.ensureDir(destDir);
+    await fs.copy(srcCommonDir, destDir, { overwrite: true });
+    console.log(chalk.green(`✓ Documentation copied to .aiflow/docs`));
+}
+
+/**
+ * Scan the project directory to guess the framework.
+ * Returns a framework key or null if undetected.
+ */
+async function detectFramework(projectDir) {
+    // JS / TS — check package.json dependencies
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = await fs.readJson(pkgPath).catch(() => ({}));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps['next'])          return 'nextjs';
+        if (deps['nuxt'])          return 'vue-nuxt';
+        if (deps['vue'])           return 'vue-nuxt';
+        if (deps['@nestjs/core'])  return 'nestjs';
+        if (deps['react'])         return 'reactjs';
+        if (deps['express'] || deps['fastify']) return 'nodejs-express';
+    }
+    // Java — pom.xml / Gradle
+    if (await fs.pathExists(path.join(projectDir, 'pom.xml')))            return 'spring-boot';
+    if (await fs.pathExists(path.join(projectDir, 'build.gradle')))       return 'spring-boot';
+    if (await fs.pathExists(path.join(projectDir, 'build.gradle.kts')))   return 'spring-boot';
+    // PHP — composer.json
+    const composerPath = path.join(projectDir, 'composer.json');
+    if (await fs.pathExists(composerPath)) {
+        const composer = await fs.readJson(composerPath).catch(() => ({}));
+        if ((composer.require || {})['laravel/framework']) return 'laravel';
+        return 'php';
+    }
+    // Python
+    if (await fs.pathExists(path.join(projectDir, 'manage.py'))) return 'python-django';
+    const reqPath = path.join(projectDir, 'requirements.txt');
+    if (await fs.pathExists(reqPath)) {
+        const reqs = (await fs.readFile(reqPath, 'utf-8').catch(() => '')).toLowerCase();
+        if (reqs.includes('fastapi')) return 'python-fastapi';
+        if (reqs.includes('django'))  return 'python-django';
+        if (detectMlFromDeps(reqs)) return 'python-ml';
+        return 'python';
+    }
+    if (await fs.pathExists(path.join(projectDir, 'pyproject.toml'))) {
+        const pyproj = (await fs.readFile(path.join(projectDir, 'pyproject.toml'), 'utf-8').catch(() => ''));
+        return detectMlFromDeps(pyproj) ? 'python-ml' : 'python';
+    }
+    return null;
+}
+
+const FRAMEWORK_CHOICES = [
+    { name: 'Spring Boot (Java)', value: 'spring-boot' },
+    { name: 'React',              value: 'reactjs' },
+    { name: 'Next.js',            value: 'nextjs' },
+    { name: 'Vue / Nuxt',         value: 'vue-nuxt' },
+    { name: 'Laravel (PHP)',      value: 'laravel' },
+    { name: 'PHP',                value: 'php' },
+    { name: 'NestJS',             value: 'nestjs' },
+    { name: 'Node.js / Express',  value: 'nodejs-express' },
+    { name: 'Python',             value: 'python' },
+    { name: 'Python Django',      value: 'python-django' },
+    { name: 'Python FastAPI',     value: 'python-fastapi' },
+    { name: 'Python ML (sklearn / PyTorch / TF)', value: 'python-ml' },
+];
+
+async function copyAssetsToVersion(versionDir, framework) {
+    // ── Skills: merge upstream + custom ──────────────────────────────
+    const upstreamSkills = path.join(PKG_DIR, 'upstream', 'skills');
+    const customSkills   = path.join(PKG_DIR, 'custom',   'skills');
+
+    await fs.ensureDir(path.join(versionDir, 'skills'));
+    if (await fs.pathExists(upstreamSkills)) {
+        await fs.copy(upstreamSkills, path.join(versionDir, 'skills'), { overwrite: true });
+    }
+    if (await fs.pathExists(customSkills)) {
+        await fs.copy(customSkills, path.join(versionDir, 'skills'), { overwrite: true });
+    }
+
+    // ── Rules: common first, then language-specific override ─────────
+    const rulesTarget    = path.join(versionDir, 'rules');
+    const commonRules    = path.join(PKG_DIR, 'custom', 'rules', 'common');
+    const allRules       = path.join(PKG_DIR, 'custom', 'rules');
+
+    await fs.ensureDir(rulesTarget);
+
+    if (await fs.pathExists(commonRules)) {
+        await fs.copy(commonRules, rulesTarget, { overwrite: true });
+    } else {
+        const entries = await fs.readdir(allRules, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                await fs.copy(
+                    path.join(allRules, entry.name),
+                    path.join(rulesTarget, entry.name),
+                    { overwrite: true }
+                );
+            }
+        }
+    }
+
+    if (framework) {
+        const lang = FRAMEWORK_LANGUAGE[framework];
+        if (lang) {
+            const langRules = path.join(PKG_DIR, 'custom', 'rules', lang);
+            if (await fs.pathExists(langRules)) {
+                await fs.copy(langRules, rulesTarget, { overwrite: true });
+                console.log(chalk.gray(`  ✓ Applied ${lang} rules`));
+            }
+        }
+    }
+}
+
+async function updateSymlinks(projectDir, versionDir) {
+    const claudeDir = path.join(projectDir, '.claude');
+    await fs.emptyDir(claudeDir);
+    await fs.copy(path.join(versionDir, 'skills'), path.join(claudeDir, 'skills'), { overwrite: true });
+
+    const rulesDir = path.join(projectDir, '.rules');
+    await fs.emptyDir(rulesDir);
+    await fs.copy(path.join(versionDir, 'rules'), rulesDir, { overwrite: true });
+
+    await setupSuperpowersHook(projectDir, claudeDir);
+
+    await fs.writeJson(path.join(projectDir, '.aiflow', 'state.json'), {
+        current_version: PKG_VERSION,
+        framework: null,
+    });
+}
+
+async function setupSuperpowersHook(_projectDir, claudeDir) {
+    const hooksDir = path.join(claudeDir, 'hooks');
+    await fs.ensureDir(hooksDir);
+
+    const hookStartSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
+    const hookStartDest = path.join(hooksDir, 'session-start.js');
+    await fs.copy(hookStartSrc, hookStartDest, { overwrite: true });
+
+    const hookStopSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-stop.js');
+    const hookStopDest = path.join(hooksDir, 'session-stop.js');
+    await fs.copy(hookStopSrc, hookStopDest, { overwrite: true });
+
+    const hookBlockGitSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'block-git-write.js');
+    const hookBlockGitDest = path.join(hooksDir, 'block-git-write.js');
+    await fs.copy(hookBlockGitSrc, hookBlockGitDest, { overwrite: true });
+
+    // Copy telemetry module so hooks can require('../telemetry/record')
+    const telemetrySrc  = path.join(PKG_DIR, 'scripts', 'telemetry');
+    const telemetryDest = path.join(claudeDir, 'telemetry');
+    await fs.copy(telemetrySrc, telemetryDest, { overwrite: true });
+
+    const settingsFile = path.join(claudeDir, 'settings.json');
+    let settings = {};
+    if (await fs.pathExists(settingsFile)) {
+        settings = await fs.readJson(settingsFile).catch(() => ({}));
+    }
+
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+    if (!settings.hooks.SessionEnd) settings.hooks.SessionEnd = [];
+    if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+    // Remove legacy SessionStop entries if present
+    if (settings.hooks.SessionStop) delete settings.hooks.SessionStop;
+
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+        h => !(h._aiflowKit)
+    );
+    settings.hooks.SessionStart.push({
+        _aiflowKit: true,
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookStartDest.replace(/\\/g, '/')}"`,
+            }
+        ]
+    });
+
+    settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(
+        h => !(h._aiflowKit)
+    );
+    settings.hooks.SessionEnd.push({
+        _aiflowKit: true,
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookStopDest.replace(/\\/g, '/')}"`,
+            }
+        ]
+    });
+
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+        h => !(h._aiflowKitBlockGitWrite)
+    );
+    settings.hooks.PreToolUse.push({
+        _aiflowKitBlockGitWrite: true,
+        matcher: 'Bash',
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookBlockGitDest.replace(/\\/g, '/')}"`,
+            }
+        ]
+    });
+
+    await fs.writeJson(settingsFile, settings, { spaces: 2 });
+    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionEnd, PreToolUse:block-git-write) configured`));
+}
+
+async function verifySuperpowersSkills(versionDir) {
+    const usingSuperpowers = path.join(versionDir, 'skills', 'using-superpowers', 'SKILL.md');
+    if (await fs.pathExists(usingSuperpowers)) {
+        console.log(chalk.green(`✓ Superpowers skills ready (built-in)`));
+    } else {
+        console.log(chalk.yellow(`! Superpowers skills missing — upstream folder may be empty`));
+    }
+}
+
+
+async function generateSkillRegistry(projectDir) {
+    const skillsDir = path.join(projectDir, '.claude', 'skills');
+    
+    if (!(await fs.pathExists(skillsDir))) return '';
+
+    let registry = `## AI Skill Registry (Superpowers)\n\n`;
+    registry += `I have access to specialized development skills. When a workflow step mentions a skill, read its \`SKILL.md\` file at the path below and follow its instructions exactly.\n\n`;
+    registry += `| Skill | Description | Instruction Path |\n`;
+    registry += `|-------|-------------|------------------|\n`;
+
+    const skillFolders = await fs.readdir(skillsDir);
+    for (const folder of skillFolders) {
+        const skillFile = path.join(skillsDir, folder, 'SKILL.md');
+        if (await fs.pathExists(skillFile)) {
+            const content = await fs.readFile(skillFile, 'utf-8');
+            let description = '';
+            
+            // Extract description from frontmatter or first paragraph
+            const descMatch = content.match(/description:\s*(.*)/i);
+            if (descMatch) {
+                description = descMatch[1].trim();
+            } else {
+                const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('---'));
+                description = lines[0] ? lines[0].trim() : 'No description available';
+            }
+
+            // Path relative to project root
+            const relPath = path.relative(projectDir, skillFile).replace(/\\/g, '/');
+            registry += `| **${folder}** | ${description} | \`${relPath}\` |\n`;
+        }
+    }
+    registry += `\n`;
+    return registry;
+}
+
+async function setupFramework(projectDir, framework, multi = false, selectedTools = Object.keys(AI_TOOL_FILES), options = {}) {
+    if (!framework) return;
+    const frameworkTemplatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
+    if (!(await fs.pathExists(frameworkTemplatePath))) {
+        console.log(chalk.yellow(`! No template found for framework: ${framework}`));
+        return;
+    }
+
+    const frameworkContent = await fs.readFile(frameworkTemplatePath, 'utf-8');
+    const workflowFile = resolveWorkflowFile(framework);
+    const workflowPath = path.join(PKG_DIR, 'custom', 'templates', 'shared', workflowFile);
+    const workflowContent = (await fs.pathExists(workflowPath))
+        ? await fs.readFile(workflowPath, 'utf-8')
+        : '';
+
+    const separator = `\n\n---\n\n`;
+    const skillRegistry = await generateSkillRegistry(projectDir);
+
+    const markerStart = '<!-- aiflow-kit-start -->';
+    const markerEnd   = '<!-- aiflow-kit-end -->';
+
+    const written = [];
+    const skipped = [];
+
+    // ── FORCE MODE: used by `aiflow update` and `sync-skills` ──────────────────
+    // Backup existing files then overwrite all — no per-file prompts.
+    if (options.force && !multi) {
+        // Phase 1: collect existing files for the summary message
+        const toOverwrite = [];
+        for (const tool of selectedTools) {
+            if (!AI_TOOL_FILES[tool]) continue;
+            const tp = path.join(projectDir, AI_TOOL_FILES[tool]);
+            if (await fs.pathExists(tp)) {
+                toOverwrite.push(path.relative(projectDir, tp).replace(/\\/g, '/'));
+            }
+        }
+
+        // Phase 2: single confirm before touching anything
+        if (toOverwrite.length > 0) {
+            console.log(chalk.yellow('\n  The following AI instruction files will be overwritten:'));
+            toOverwrite.forEach(f => console.log(chalk.yellow(`    • ${f}`)));
+            console.log(chalk.gray('  Current content will be backed up to .aiflow/bk/'));
+            const proceed = await confirm({ message: 'Proceed with overwrite?', default: true });
+            if (!proceed) {
+                console.log(chalk.gray('  Skipped AI instruction file update.'));
+                return;
+            }
+        }
+
+        // Phase 3: backup + write each tool file
+        for (const tool of selectedTools) {
+            if (!AI_TOOL_FILES[tool]) continue;
+            const targetPath = path.join(projectDir, AI_TOOL_FILES[tool]);
+            await fs.ensureDir(path.dirname(targetPath));
+
+            // Build content for this tool
+            let finalContent = '';
+            const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
+            if (await fs.pathExists(toolTemplatePath)) {
+                finalContent += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
+            }
+            finalContent += frameworkContent + '\n\n';
+            if (skillRegistry) finalContent += skillRegistry + '\n\n';
+            if (workflowContent) finalContent += workflowContent + '\n\n';
+            finalContent = `${markerStart}\n${finalContent.trim()}\n${markerEnd}`;
+
+            // Backup existing file before overwriting
+            if (await fs.pathExists(targetPath)) {
+                const bkDir = path.join(projectDir, '.aiflow', 'bk');
+                await fs.ensureDir(bkDir);
+                const iso = new Date().toISOString();
+                const ts = iso.slice(0, 10) + '_' + iso.slice(11, 16).replace(':', '-');
+                const bkName = `${ts}_${path.basename(targetPath)}`;
+                await fs.copy(targetPath, path.join(bkDir, bkName));
+                const relPath = path.relative(projectDir, targetPath).replace(/\\/g, '/');
+                console.log(chalk.gray(`  ⟳ Backed up ${relPath} → .aiflow/bk/${bkName}`));
+            }
+
+            await fs.writeFile(targetPath, finalContent);
+            const relPath = path.relative(projectDir, targetPath).replace(/\\/g, '/');
+            console.log(chalk.green(`  ✓ Overwrote ${relPath}`));
+            written.push(AI_TOOL_FILES[tool]);
+        }
+
+        if (written.length) {
+            console.log(chalk.green(`✓ AI instruction files updated for framework: ${framework} (${written.join(', ')})`));
+        }
+        return;
+    }
+
+    // ── INTERACTIVE MODE: used by `aiflow init` ─────────────────────────────────
+    for (const tool of selectedTools) {
+        const targetPath = path.join(projectDir, AI_TOOL_FILES[tool]);
+        if (!targetPath) continue;
+
+        await fs.ensureDir(path.dirname(targetPath));
+
+        let finalContent = '';
+
+        const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
+        if (await fs.pathExists(toolTemplatePath)) {
+            finalContent += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
+        }
+
+        // Include framework conventions for single-framework projects
+        if (!multi && frameworkContent) {
+            finalContent += frameworkContent + '\n\n';
+        }
+
+        if (skillRegistry) {
+            finalContent += skillRegistry + '\n\n';
+        }
+
+        if (workflowContent) {
+            finalContent += workflowContent + '\n\n';
+        }
+
+        finalContent = `${markerStart}\n${finalContent.trim()}\n${markerEnd}`;
+
+        const fileExists = await fs.pathExists(targetPath);
+
+        if (!multi) {
+            const relPath = path.relative(projectDir, targetPath).replace(/\\/g, '/');
+            if (fileExists) {
+                const existingContent = await fs.readFile(targetPath, 'utf-8');
+                const hasStart = existingContent.includes(markerStart);
+                const hasEnd = existingContent.includes(markerEnd);
+
+                if (hasStart && hasEnd) {
+                    const doUpdate = await confirm({
+                        message: `File ${relPath} already contains an AI Flow block. Do you want to update this block? (Your custom rules will not be affected)`,
+                        default: true
+                    });
+                    if (doUpdate) {
+                        const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`, 'g');
+                        const updatedContent = existingContent.replace(regex, finalContent);
+                        await fs.writeFile(targetPath, updatedContent);
+                        console.log(chalk.green(`  ✓ Updated AI Flow block in ${relPath}`));
+                        written.push(AI_TOOL_FILES[tool]);
+                    } else {
+                        const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
+                        await fs.ensureDir(path.dirname(refPath));
+                        await fs.writeFile(refPath, finalContent);
+                        const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
+                        console.log(chalk.gray(`  ✓ Skipped ${relPath} — aiflow template saved to ${refRel}`));
+                        skipped.push(relPath);
+                    }
+                } else {
+                    const doOverwrite = await confirm({
+                        message: `File ${relPath} is missing the new AI Flow marker block. Do you want to OVERWRITE it completely with the latest template?`,
+                        default: true
+                    });
+                    if (doOverwrite) {
+                        await fs.writeFile(targetPath, finalContent);
+                        console.log(chalk.green(`  ✓ Overwrote ${relPath} with latest AI Flow template`));
+                        written.push(AI_TOOL_FILES[tool]);
+                    } else {
+                        const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
+                        await fs.ensureDir(path.dirname(refPath));
+                        await fs.writeFile(refPath, finalContent);
+                        const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
+                        console.log(chalk.gray(`  ✓ Skipped ${relPath} — aiflow template saved to ${refRel}`));
+                        skipped.push(relPath);
+                    }
+                }
+            } else {
+                const doCreate = await confirm({
+                    message: `File ${relPath} does not exist. Do you want to create it using the latest AI Flow template?`,
+                    default: true
+                });
+                if (doCreate) {
+                    await fs.writeFile(targetPath, finalContent);
+                    written.push(AI_TOOL_FILES[tool]);
+                }
+            }
+        } else {
+            if (fileExists) {
+                await fs.appendFile(targetPath, separator + frameworkContent);
+            } else {
+                await fs.writeFile(targetPath, finalContent);
+            }
+            written.push(AI_TOOL_FILES[tool]);
+        }
+    }
+
+    if (written.length) {
+        console.log(chalk.green(`✓ AI instruction files updated for framework: ${framework} (${written.join(', ')})`));
+    }
+    if (skipped.length) {
+        console.log(chalk.yellow(`  Skipped (kept existing): ${skipped.join(', ')}`));
+    }
+}
+
+async function setupAdapter(projectDir, adapter) {
+    if (!adapter) return;
+    const presetPath = path.join(PKG_DIR, 'custom', 'mcp-presets', `${adapter}.json`);
+    if (!(await fs.pathExists(presetPath))) {
+        console.log(chalk.yellow(`! No MCP preset found for adapter: ${adapter}`));
+        return;
+    }
+
+    const { mcpServers } = await fs.readJson(presetPath);
+    const serverKey    = Object.keys(mcpServers)[0];
+    const serverConfig = mcpServers[serverKey];
+
+    let existingCreds = {};
+    if (await fs.pathExists(GLOBAL_CREDENTIALS_PATH)) {
+        const globalData = await fs.readJson(GLOBAL_CREDENTIALS_PATH).catch(() => ({}));
+        existingCreds = globalData.mcp || {};
+    }
+
+    console.log(chalk.cyan(`\nSetup MCP adapter for ${adapter}:`));
+    console.log(chalk.gray('Press Enter to keep existing value shown in [brackets]\n'));
+
+    const credentials = {};
+    for (const [envKey] of Object.entries(serverConfig.env)) {
+        const current = existingCreds[envKey];
+        const hint = current
+            ? `[${maskSecret(current)}]`
+            : chalk.gray('[not set — required]');
+
+        let resolved = '';
+        while (true) {
+            const value = await input({
+                message: `${envKey} ${hint}:`,
+                default: '',
+            });
+            resolved = value.trim() || current || '';
+            if (resolved) break;
+            console.log(chalk.red(`  ✗ ${envKey} is required. Please enter a value.`));
+        }
+        serverConfig.env[envKey] = resolved;
+        credentials[envKey] = resolved;
+    }
+
+    console.log(chalk.cyan(`\nVerifying ${adapter} credentials...`));
+    const verifyResult = await verifyAdapterCredentials(adapter, credentials);
+    if (!verifyResult.ok) {
+        console.log(chalk.red(`✗ Verification failed: ${verifyResult.error}`));
+        console.log(chalk.yellow('  Credentials saved but may not work. Re-run `aiflow init --adapter ' + adapter + '` to update.'));
+    } else {
+        console.log(chalk.green(`✓ Credentials verified successfully`));
+    }
+
+    const claudeConfigDir = path.join(
+        process.env.APPDATA ||
+        (process.platform === 'darwin'
+            ? process.env.HOME + '/Library/Application Support'
+            : process.env.HOME + '/.config'),
+        'Claude'
+    );
+    const mcpConfigFile = path.join(claudeConfigDir, 'claude_desktop_config.json');
+    let existingConfig = { mcpServers: {} };
+    if (await fs.pathExists(mcpConfigFile)) {
+        existingConfig = await fs.readJson(mcpConfigFile).catch(() => ({ mcpServers: {} }));
+    }
+    if (!existingConfig.mcpServers) existingConfig.mcpServers = {};
+    existingConfig.mcpServers[serverKey] = serverConfig;
+    await fs.ensureDir(path.dirname(mcpConfigFile));
+    await fs.writeJson(mcpConfigFile, existingConfig, { spaces: 2 });
+
+    await fs.writeJson(
+        path.join(projectDir, '.mcp.json'),
+        { mcpServers: { [serverKey]: serverConfig } },
+        { spaces: 2 }
+    );
+
+    await fs.ensureDir(GLOBAL_AIFLOW_DIR);
+    let globalData = {};
+    if (await fs.pathExists(GLOBAL_CREDENTIALS_PATH)) {
+        globalData = await fs.readJson(GLOBAL_CREDENTIALS_PATH).catch(() => ({}));
+    }
+    globalData.mcp = { ...(globalData.mcp || {}), ...credentials };
+    await fs.writeJson(GLOBAL_CREDENTIALS_PATH, globalData, { spaces: 2 });
+    await ensureAiflowGitignored(projectDir);
+
+    console.log(chalk.green(`✓ MCP configuration saved (global + local + credentials).`));
+}
+
+async function verifyAdapterCredentials(adapter, credentials) {
+    try {
+        if (adapter === 'backlog') return await verifyBacklog(credentials);
+        if (adapter === 'jira') return await verifyJira(credentials);
+        if (adapter === 'figma') return await verifyFigma(credentials);
+        return { ok: true };
+    } catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+
+function verifyBacklog(credentials) {
+    const https = require('https');
+    const apiKey   = credentials.BACKLOG_API_KEY;
+    const spaceKey = credentials.BACKLOG_SPACE_KEY;
+    const domain   = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
+
+    return new Promise((resolve) => {
+        const url = `https://${domain}/api/v2/users/myself?apiKey=${apiKey}`;
+        const req = https.get(url, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    const user = JSON.parse(data);
+                    resolve({ ok: true, user: user.name });
+                } else if (res.statusCode === 401) {
+                    resolve({ ok: false, error: 'Invalid API key' });
+                } else if (res.statusCode === 404) {
+                    resolve({ ok: false, error: `Space "${spaceKey}" not found` });
+                } else {
+                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
+                }
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, error: err.message }));
+        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
+    });
+}
+
+function verifyJira(credentials) {
+    const https = require('https');
+    const { JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN } = credentials;
+    const auth = Buffer.from(`${JIRA_EMAIL}:${JIRA_API_TOKEN}`).toString('base64');
+
+    return new Promise((resolve) => {
+        const options = {
+            hostname: `${JIRA_DOMAIN}.atlassian.net`,
+            path: '/rest/api/3/myself',
+            headers: { 'Authorization': `Basic ${auth}`, 'Accept': 'application/json' },
+        };
+        const req = https.get(options, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    resolve({ ok: true });
+                } else if (res.statusCode === 401) {
+                    resolve({ ok: false, error: 'Invalid email or API token' });
+                } else {
+                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
+                }
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, error: err.message }));
+        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
+    });
+}
+
+function verifyFigma(credentials) {
+    const https = require('https');
+    const { FIGMA_API_TOKEN } = credentials;
+
+    return new Promise((resolve) => {
+        const options = {
+            hostname: 'api.figma.com',
+            path: '/v1/me',
+            headers: { 'X-Figma-Token': FIGMA_API_TOKEN },
+        };
+        const req = https.get(options, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    const user = JSON.parse(data);
+                    resolve({ ok: true, user: user.name || user.email });
+                } else if (res.statusCode === 403 || res.statusCode === 401) {
+                    resolve({ ok: false, error: 'Invalid Figma API token' });
+                } else {
+                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
+                }
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, error: err.message }));
+        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
+    });
+}
+
+async function ensureAiflowGitignored(projectDir) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    const entries = [
+        '.aiflow/',
+        'plan/',
+        '.claude/',
+        '.rules/',
+        '.mcp.json',
+        'CLAUDE.md',
+        'GEMINI.md',
+        '.cursorrules',
+        '.github/copilot-instructions.md'
+    ];
+    let content = '';
+    if (await fs.pathExists(gitignorePath)) {
+        content = await fs.readFile(gitignorePath, 'utf-8');
+    }
+    const lines = content.split('\n').map(l => l.trim());
+    let changed = false;
+    let separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+
+    for (const entry of entries) {
+        if (!lines.includes(entry)) {
+            content += `${separator}${entry}\n`;
+            separator = '';
+            changed = true;
+            console.log(chalk.yellow(`  ⚠ Added ${entry} to .gitignore`));
+        }
+    }
+    if (changed) {
+        await fs.writeFile(gitignorePath, content);
+    }
+}
+
+function maskSecret(value) {
+    if (!value || value.length <= 8) return '***';
+    return `${value.slice(0, 4)}***${value.slice(-4)}`;
+}
+
+// ── GitNexus (code intelligence) helpers ─────────────────────────
+
+const IGNORE_DIRS = new Set([
+    '.git', 'node_modules', 'target', 'build', '.aiflow',
+    'dist', 'out', '.next', '.nuxt', 'vendor', 'coverage', '.gradle',
+]);
+const SOURCE_EXT = /\.(java|kt|groovy|js|ts|jsx|tsx|mjs|cjs|php|py|go|rb|cs|cpp|c|h|rs|vue|svelte|xml|yml|yaml|sql|properties)$/i;
+async function countSourceFiles(dir) {
+    let count = 0;
+    const scan = async (d) => {
+        let entries;
+        try { entries = await fs.readdir(d, { withFileTypes: true }); } catch (_) { return; }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (!IGNORE_DIRS.has(e.name) && !e.name.startsWith('.')) await scan(path.join(d, e.name));
+            } else if (SOURCE_EXT.test(e.name)) {
+                count++;
+            }
+        }
+    };
+    await scan(dir);
+    return count;
+}
+
+async function isGitNexusConfigured(projectDir) {
+    const mcpPath = path.join(projectDir, '.mcp.json');
+    if (!(await fs.pathExists(mcpPath))) return false;
+    const mcp = await fs.readJson(mcpPath).catch(() => ({}));
+    return !!(mcp.mcpServers && mcp.mcpServers.gitnexus);
+}
+
+async function setupGitNexus(projectDir, wait = false) {
+    const { spawn } = require('child_process');
+    // On Windows, use shell:true so npm scripts (.cmd) resolve correctly — avoids EINVAL
+    const isWin   = process.platform === 'win32';
+    const npxCmd  = 'npx';
+    const spawnOpts = (extra = {}) => ({ shell: isWin, windowsHide: true, ...extra });
+
+    // 1. Inject MCP server config into .mcp.json (merge, don't overwrite)
+    const mcpPath = path.join(projectDir, '.mcp.json');
+    let existing = {};
+    if (await fs.pathExists(mcpPath)) {
+        existing = await fs.readJson(mcpPath).catch(() => ({}));
+    }
+    if (!existing.mcpServers) existing.mcpServers = {};
+    const mcpAlreadyPresent = !!(existing.mcpServers.gitnexus);
+    
+    // 3. Detect if gitnexus is already available in PATH (preferred over npx)
+    const hasGlobalGitNexus = commandExists('gitnexus');
+    if (hasGlobalGitNexus) {
+        existing.mcpServers.gitnexus = { command: 'gitnexus', args: ['mcp'] };
+        console.log(chalk.gray('  ✓ Global gitnexus found — using it for MCP and indexing.'));
+    } else {
+        existing.mcpServers.gitnexus = { command: 'npx', args: ['-y', 'gitnexus@latest', 'mcp'] };
+    }
+    await fs.writeJson(mcpPath, existing, { spaces: 2 });
+    if (!mcpAlreadyPresent) {
+        console.log(chalk.green('✓ GitNexus MCP server configured (.mcp.json)'));
+    }
+
+    const nodeMajor = parseInt(process.version.slice(1).split('.')[0], 10);
+    if (nodeMajor < 20) {
+        console.log(chalk.yellow(`⚠ GitNexus indexing skipped — requires Node.js >=20.0.0 (current: ${process.version}).`));
+        console.log(chalk.gray('  MCP config saved. After upgrading Node.js, run: npx gitnexus analyze'));
+        return;
+    }
+
+    const aiflowDir = path.join(projectDir, '.aiflow');
+    await fs.ensureDir(aiflowDir);
+    const statusPath  = path.join(aiflowDir, 'gitnexus-status.json');
+    const startedAt   = new Date().toISOString();
+    await fs.writeJson(statusPath, { status: 'running', startedAt });
+
+    if (!wait) {
+        const workerPath = path.join(__dirname, 'gitnexus-worker.js');
+        const child = spawn(process.execPath, [workerPath, projectDir],
+            spawnOpts({ detached: true, stdio: 'ignore' }));
+        child.unref();
+        console.log(chalk.cyan('⟳ GitNexus: indexing codebase in background...'));
+        console.log(chalk.gray('  Notification will appear when you run `aiflow use <TICKET>` next time.'));
+        return;
+    }
+
+    const fileCount = await countSourceFiles(projectDir);
+    console.log(chalk.cyan(`⟳ GitNexus: indexing ${fileCount} source files (this may take 10–30 min on first run)...`));
+    console.log(chalk.gray('  Remove --wait to index in background instead.'));
+
+    await new Promise((resolve) => {
+        const runIndexing = (withMoreRam = false) => {
+            const currentCmd = hasGlobalGitNexus ? 'gitnexus' : 'npx';
+            const currentArgs = hasGlobalGitNexus ? ['analyze'] : ['-y', 'gitnexus@latest', 'analyze'];
+            const env = { ...process.env };
+            if (withMoreRam) {
+                const ramSize = withMoreRam === '8g' ? '8192' : '4096';
+                env.NODE_OPTIONS = `--max-old-space-size=${ramSize}`;
+            }
+
+            const child = spawn(currentCmd, currentArgs,
+                spawnOpts({ cwd: projectDir, stdio: ['ignore', 'inherit', 'inherit'], env }));
+
+            child.on('close', async (code) => {
+                const completedAt = new Date().toISOString();
+                if (code === 0) {
+                    await fs.writeJson(statusPath, { status: 'done', startedAt, completedAt, notified: true });
+                    console.log(chalk.green(`✓ GitNexus: indexed ${fileCount} files — code intelligence is ready.`));
+                    resolve();
+                } else {
+                    console.log(chalk.red(`✗ GitNexus: indexing failed (exit ${code}).`));
+
+                    // Detection of Segmentation Fault / Crash (139 on Linux/Mac, 3221225477 on Windows)
+                    const isCrash = (code === 139 || code === 3221225477);
+                    if (isCrash) {
+                        console.log(chalk.yellow(`\n⚠ Indexing crashed (Segmentation Fault) at ${withMoreRam ? (withMoreRam === '8g' ? '8GB' : '4GB') : 'default'} RAM.`));
+                        
+                        const nextRam = !withMoreRam ? '4g' : (withMoreRam === '4g' ? '8g' : null);
+                        if (nextRam) {
+                            const retry = await confirm({ 
+                                message: `Would you like to retry indexing with increased memory (${nextRam.toUpperCase()})?`, 
+                                default: true 
+                            });
+                            if (retry) {
+                                return runIndexing(nextRam); // Recursion, don't resolve yet
+                            }
+                        } else {
+                            console.log(chalk.red('⚠ Already tried with 8GB RAM. Please check if there are any extremely large files or corrupted database.'));
+                            console.log(chalk.gray('  Try: rm -rf .aiflow/ladybug.db (if exists) or check your .gitignore'));
+                        }
+                    }
+
+                    // If npx failed and gitnexus isn't global, offer to install it global (only if not a crash or if retry was rejected)
+                    if (!hasGlobalGitNexus && !isCrash) {
+                        console.log(chalk.yellow('\nTip: npx failed. Installing gitnexus globally often fixes environment issues.'));
+                        const install = await confirm({ message: 'Would you like me to try installing gitnexus globally for you?', default: true });
+                        if (install) {
+                            try {
+                                console.log(chalk.blue('Running: npm install -g gitnexus ...'));
+                                execSync('npm install -g gitnexus', { stdio: 'inherit' });
+                                console.log(chalk.green('✓ GitNexus installed globally. Please run `aiflow init` again to retry indexing.'));
+                            } catch (err) {
+                                console.log(chalk.red('Failed to install globally. Please try manually: npm install -g gitnexus'));
+                            }
+                        }
+                    }
+
+                    await fs.writeJson(statusPath, { status: 'error', startedAt, completedAt, exitCode: code, notified: true });
+                    resolve();
+                }
+            });
+
+            child.on('error', async (err) => {
+                await fs.writeJson(statusPath, {
+                    status: 'error', startedAt, completedAt: new Date().toISOString(),
+                    exitCode: null, error: err.message, notified: true,
+                });
+                console.log(chalk.red(`✗ GitNexus: failed to start — ${err.message}`));
+                resolve();
+            });
+        };
+
+        runIndexing();
+    });
+}
+
+async function maybeSetupGitNexus(projectDir, withGitNexus, wait = false) {
+    if (!withGitNexus) return;
+
+    // Check if indexing has already completed successfully (not stale)
+    const STALE_MS   = 3 * 60 * 60 * 1000;
+    const statusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
+    let indexDone = false;
+    try {
+        const gn  = await fs.readJson(statusPath);
+        const age = gn.startedAt ? Date.now() - new Date(gn.startedAt).getTime() : Infinity;
+        const staleRunning = gn.status === 'running' && age > STALE_MS;
+        indexDone = gn.status === 'done' && !staleRunning;
+    } catch (_) {}
+
+    if ((await isGitNexusConfigured(projectDir)) && indexDone) {
+        console.log(chalk.gray('  GitNexus already configured and indexed — skipping.'));
+        return;
+    }
+    await setupGitNexus(projectDir, wait);
+}
+
+// ── RTK (token compression) helpers ──────────────────────────────
+
+async function detectRtk() {
+    const { execSync } = require('child_process');
+    try {
+        const out = execSync('rtk --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        return { installed: true, version: out.replace(/^rtk\s*/i, '') };
+    } catch (_) {
+        return { installed: false };
+    }
+}
+
+async function isRtkHookConfigured(projectDir) {
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    if (!(await fs.pathExists(settingsPath))) return false;
+    const settings = await fs.readJson(settingsPath).catch(() => ({}));
+    const preHooks = settings?.hooks?.PreToolUse || [];
+    return preHooks.some(h =>
+        (h.hooks || []).some(entry =>
+            typeof entry.command === 'string' && entry.command.includes('rtk')
+        )
+    );
+}
+
+async function setupRtkHook(projectDir) {
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    let settings = {};
+    if (await fs.pathExists(settingsPath)) {
+        settings = await fs.readJson(settingsPath).catch(() => ({}));
+    }
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+    const alreadySet = settings.hooks.PreToolUse.some(h =>
+        (h.hooks || []).some(e => typeof e.command === 'string' && e.command.includes('rtk'))
+    );
+    if (alreadySet) return;
+
+    settings.hooks.PreToolUse.push({
+        matcher: 'Bash',
+        hooks: [{ type: 'command', command: 'rtk rewrite' }],
+    });
+    await fs.ensureDir(path.join(projectDir, '.claude'));
+    await fs.writeJson(settingsPath, settings, { spaces: 2 });
+    console.log(chalk.green('✓ RTK token compression hook configured (.claude/settings.json)'));
+}
+
+async function maybeSetupRtk(projectDir, forceSetup) {
+    const rtk = await detectRtk();
+    if (!rtk.installed && !forceSetup) return;
+
+    if (forceSetup && !rtk.installed) {
+        console.log(chalk.yellow('⚠ --with-rtk specified but rtk binary not found. Install: cargo install rtk'));
+        return;
+    }
+
+    if (await isRtkHookConfigured(projectDir)) {
+        console.log(chalk.gray('  RTK hook already configured — skipping.'));
+        return;
+    }
+
+    const enable = forceSetup || await confirm({
+        message: `RTK detected (${rtk.version}). Enable token compression for Claude Code?`,
+        default: true,
+    });
+    if (enable) await setupRtkHook(projectDir);
+}
+
+async function init(options) {
+    const projectDir = process.cwd();
+    const aiflowDir  = path.join(projectDir, '.aiflow');
+    let frameworks = options.frameworks || (options.framework ? [options.framework] : []);
+    const adapters = options.adapters   || (options.adapter   ? [options.adapter]   : []);
+
+    try {
+        console.log(chalk.blue(`Initializing ai-flow-kit (v${PKG_VERSION})...`));
+
+        // ── Auto-detect or prompt for framework if not supplied ──────
+        if (frameworks.length === 0) {
+            const stateFilePath = path.join(aiflowDir, 'state.json');
+            let previousFrameworks = [];
+            if (await fs.pathExists(stateFilePath)) {
+                const savedState = await fs.readJson(stateFilePath);
+                // Support both old 'framework' (singular string) and new 'frameworks' (array)
+                previousFrameworks = savedState.frameworks || (savedState.framework ? [savedState.framework] : []);
+            }
+
+            const detected = await detectFramework(projectDir);
+            const hint = chalk.gray('  Space to select/unselect · Enter to confirm · Leave empty to skip');
+            if (previousFrameworks.length > 0) {
+                const labels = previousFrameworks
+                    .map(v => FRAMEWORK_CHOICES.find(c => c.value === v)?.name || v)
+                    .join(', ');
+                console.log(chalk.cyan(`\n  Previously selected: ${chalk.bold(labels)}`));
+                console.log(hint);
+            } else if (detected) {
+                const label = FRAMEWORK_CHOICES.find(c => c.value === detected)?.name || detected;
+                console.log(chalk.cyan(`\n  Detected framework: ${chalk.bold(label)}`));
+                console.log(hint);
+            } else {
+                console.log(chalk.gray('\n  No framework detected.'));
+                console.log(hint);
+            }
+            const chosen = await checkbox({
+                message: 'Select framework(s):',
+                choices: FRAMEWORK_CHOICES.map(c => ({
+                    ...c,
+                    checked: previousFrameworks.length > 0
+                        ? previousFrameworks.includes(c.value)
+                        : c.value === detected,
+                })),
+            });
+            frameworks = chosen;
+        }
+
+        const primaryFramework = frameworks[0] || null;
+        const versionDir = path.join(aiflowDir, 'versions', PKG_VERSION);
+
+        if (frameworks.length) console.log(chalk.gray(`  Frameworks: ${frameworks.join(', ')}`));
+        if (adapters.length)   console.log(chalk.gray(`  Adapters:   ${adapters.join(', ')}`));
+
+        await fs.ensureDir(versionDir);
+        await copyAssetsToVersion(versionDir, primaryFramework);
+        await verifySuperpowersSkills(versionDir);
+        await updateSymlinks(projectDir, versionDir);
+        await copyDocsToProject(projectDir);
+
+        const selectedTools = options.aiTools || Object.keys(AI_TOOL_FILES);
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools, { force: true });
+        }
+        for (const adapter of adapters) {
+            await setupAdapter(projectDir, adapter);
+        }
+
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (await fs.pathExists(stateFile)) {
+            const state = await fs.readJson(stateFile);
+            state.frameworks = frameworks;
+            state.adapters   = adapters;
+            state.aiTools    = selectedTools;
+            await fs.writeJson(stateFile, state);
+        }
+
+        // ── Optional: RTK token compression ─────────────────────────
+        // Commander sets options.rtk=false when --no-rtk is passed
+        if (options.rtk !== false) {
+            await maybeSetupRtk(projectDir, options.withRtk || false);
+        }
+
+        // ── Optional: GitNexus code intelligence ─────────────────────
+        await maybeSetupGitNexus(projectDir, options.withGitnexus || false, options.wait || false);
+
+        // ── Ensure all aiflow files are gitignored ───────────────────
+        await ensureAiflowGitignored(projectDir);
+
+        console.log(chalk.green('\n✨ Initialized AI Flow Kit successfully!'));
+        console.log(chalk.blue('\n' + '─'.repeat(62)));
+        console.log(chalk.bold.white('  Next steps:'));
+
+        if (adapters.length > 0) {
+            console.log(`  ${chalk.green('aiflow use PROJ-33')}    ${chalk.gray('← load ticket from ' + adapters.join('/'))} `);
+        } else {
+            console.log(`  ${chalk.green('aiflow use --manual')}   ${chalk.gray('← input ticket content in terminal')}`);
+            console.log(`  ${chalk.green('aiflow use --file req.md')} ${chalk.gray('← load from local file')}`);
+        }
+
+        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← Claude Code CLI (recommended)')}`);
+        console.log(`  ${chalk.green('Cursor / Gemini')}       ${chalk.gray('← Instructions in .cursorrules / GEMINI.md')}`);
+        console.log(chalk.blue('─'.repeat(62)));
+        console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Commands: ${chalk.green('aiflow guide --commands')}`));
+        console.log(chalk.blue('─'.repeat(62)) + '\n');
+    } catch (err) {
+        console.error(chalk.red(`Error during initialization: ${err.message}`));
+    }
+}
+
+module.exports = init;
+module.exports.AI_TOOL_FILES = AI_TOOL_FILES;
+module.exports.detectRtk = detectRtk;
+module.exports.isRtkHookConfigured = isRtkHookConfigured;
+module.exports.isGitNexusConfigured = isGitNexusConfigured;
+module.exports.setupFramework = setupFramework;
+module.exports.ensureAiflowGitignored = ensureAiflowGitignored;
+module.exports.resolveWorkflowFile = resolveWorkflowFile;
+module.exports.ML_FRAMEWORKS = ML_FRAMEWORKS;
+module.exports.FRAMEWORK_LANGUAGE = FRAMEWORK_LANGUAGE;
+module.exports.FRAMEWORK_CHOICES = FRAMEWORK_CHOICES;
+module.exports.detectMlFromDeps = detectMlFromDeps;