@relipa/ai-flow-kit 0.0.3 → 0.0.4-beta.2

package/scripts/init.js

@@ -1,453 +1,460 @@
-const fs = require('fs-extra');
-const path = require('path');
-const chalk = require('chalk');
-const { input } = require('@inquirer/prompts');
-
-const PKG_DIR = path.join(__dirname, '..');
-const PKG_VERSION = require('../package.json').version;
-
-// Map framework → language family for picking the right rules
-const FRAMEWORK_LANGUAGE = {
-    'laravel':      'php',
-    'spring-boot':  'java',
-    'reactjs':      'javascript',
-    'nextjs':       'javascript',
-    'vue-nuxt':     'javascript',
-};
-
-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);
-
-    // Copy common rules (language-agnostic) if the folder exists,
-    // otherwise fall back to copying everything at root level
-    if (await fs.pathExists(commonRules)) {
-        await fs.copy(commonRules, rulesTarget, { overwrite: true });
-    } else {
-        // Copy only .md files at root (skip sub-folders like java/, php/, javascript/)
-        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 }
-                );
-            }
-        }
-    }
-
-    // Overlay language-specific rules on top
-    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 });
-
-    // Setup SessionStart hook so superpowers auto-triggers on every session
-    await setupSuperpowersHook(projectDir, claudeDir);
-
-    await fs.writeJson(path.join(projectDir, '.aiflow', 'state.json'), {
-        current_version: PKG_VERSION,
-        framework: null,   // will be set after setupFramework
-    });
-}
-
-async function setupSuperpowersHook(_projectDir, claudeDir) {
-    // 1. Copy hook script into .claude/hooks/
-    const hooksDir = path.join(claudeDir, 'hooks');
-    await fs.ensureDir(hooksDir);
-
-    const hookSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
-    const hookDest = path.join(hooksDir, 'session-start.js');
-    await fs.copy(hookSrc, hookDest, { overwrite: true });
-
-    // 2. Merge SessionStart hook into .claude/settings.json
-    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 = [];
-
-    // Remove any stale ai-flow-kit hook entry, then add fresh one
-    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
-        h => !(h._aiflowKit)
-    );
-    settings.hooks.SessionStart.push({
-        _aiflowKit: true,   // marker so we can update it cleanly on re-init
-        hooks: [
-            {
-                type: 'command',
-                command: `node "${hookDest.replace(/\\/g, '/')}"`,
-            }
-        ]
-    });
-
-    await fs.writeJson(settingsFile, settings, { spaces: 2 });
-    console.log(chalk.green(`✓ Superpowers SessionStart hook configured`));
-}
-
-/**
- * Verify superpowers skills are present — auto-copied from upstream.
- * Developer does NOT need to install superpowers separately.
- */
-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`));
-    }
-}
-
-/**
- * Setup CLAUDE.md for a framework.
- * If multi=true (multiple frameworks), append instead of overwrite.
- */
-async function setupFramework(projectDir, framework, multi = false) {
-    if (!framework) return;
-    const templatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
-    if (!(await fs.pathExists(templatePath))) {
-        console.log(chalk.yellow(`! No template found for framework: ${framework}`));
-        return;
-    }
-
-    const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
-
-    if (!multi) {
-        // Single framework → overwrite
-        await fs.copy(templatePath, claudeMdPath);
-    } else {
-        // Multiple frameworks → append with separator
-        const content = await fs.readFile(templatePath, 'utf-8');
-        const separator = `\n\n---\n\n`;
-        if (await fs.pathExists(claudeMdPath)) {
-            await fs.appendFile(claudeMdPath, separator + content);
-        } else {
-            await fs.writeFile(claudeMdPath, content);
-        }
-    }
-
-    console.log(chalk.green(`✓ CLAUDE.md updated for framework: ${framework}`));
-}
-
-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];
-
-    // ── Load existing credentials (same pattern as `aws configure`) ──
-    const credsFile = path.join(projectDir, '.aiflow', 'credentials.json');
-    let existingCreds = {};
-    if (await fs.pathExists(credsFile)) {
-        existingCreds = await fs.readJson(credsFile).catch(() => ({}));
-    }
-
-    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];
-
-        // Show masked current value as default hint (like aws configure)
-        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;
-
-            // Empty and no existing value → reject
-            console.log(chalk.red(`  ✗ ${envKey} is required. Please enter a value.`));
-        }
-
-        serverConfig.env[envKey] = resolved;
-        credentials[envKey] = resolved;
-    }
-
-    // ── Verify credentials against real API ──────────────────────────
-    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`));
-    }
-
-    // ── 1. Save to Claude Desktop MCP config ─────────────────────────
-    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 });
-
-    // ── 2. Save locally as .mcp.json ─────────────────────────────────
-    await fs.writeJson(
-        path.join(projectDir, '.mcp.json'),
-        { mcpServers: { [serverKey]: serverConfig } },
-        { spaces: 2 }
-    );
-
-    // ── 3. Save credentials to .aiflow/credentials.json ──────────────
-    //    use.js will read from here when env vars are not set
-    Object.assign(existingCreds, credentials);
-    await fs.writeJson(credsFile, existingCreds, { spaces: 2 });
-
-    // ── 4. Ensure credentials.json is gitignored ──────────────────────
-    await ensureCredentialsGitignored(projectDir);
-
-    console.log(chalk.green(`✓ MCP configuration saved (global + local + credentials).`));
-}
-
-/**
- * Verify adapter credentials by making a lightweight API call
- */
-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);
-        }
-        // Unknown adapter — skip verification
-        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: { 'Authorization': `Bearer ${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' }); });
-    });
-}
-
-/**
- * Ensure `.aiflow/credentials.json` is listed in the project's .gitignore.
- * Appends the entry if missing, creates .gitignore if it doesn't exist.
- */
-async function ensureCredentialsGitignored(projectDir) {
-    const gitignorePath = path.join(projectDir, '.gitignore');
-    const entry = '.aiflow/credentials.json';
-
-    let content = '';
-    if (await fs.pathExists(gitignorePath)) {
-        content = await fs.readFile(gitignorePath, 'utf-8');
-    }
-
-    // Check if already ignored (exact line match)
-    const lines = content.split('\n').map(l => l.trim());
-    if (lines.includes(entry)) return;
-
-    // Append with a trailing newline
-    const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
-    await fs.appendFile(gitignorePath, `${separator}${entry}\n`);
-    console.log(chalk.yellow(`  ⚠ Added ${entry} to .gitignore (contains API keys)`));
-}
-
-/**
- * Mask a secret for display: show first 4 chars + *** + last 4 chars
- * e.g. "sAgkcqW5Bq...K5xnFvkQ7" → "sAgk***vkQ7"
- */
-function maskSecret(value) {
-    if (!value || value.length <= 8) return '***';
-    return `${value.slice(0, 4)}***${value.slice(-4)}`;
-}
-
-module.exports = async function init(options) {
-    const projectDir = process.cwd();
-    const aiflowDir  = path.join(projectDir, '.aiflow');
-    // Use primary (first) framework for language-specific rules selection
-    const frameworks = options.frameworks || (options.framework ? [options.framework] : []);
-    const adapters   = options.adapters   || (options.adapter   ? [options.adapter]   : []);
-    const primaryFramework = frameworks[0] || null;
-    const versionDir = path.join(aiflowDir, 'versions', PKG_VERSION);
-
-    try {
-        console.log(chalk.blue(`Initializing ai-flow-kit (v${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);
-
-        // Setup each framework (CLAUDE.md = last one wins, or merged)
-        for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1);
-        }
-
-        // Setup each adapter
-        for (const adapter of adapters) {
-            await setupAdapter(projectDir, adapter);
-        }
-
-        // Persist all frameworks + adapters in state
-        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;
-            await fs.writeJson(stateFile, state);
-        }
-
-        console.log(chalk.green('\n✨ Initialized AI Flow Kit successfully!'));
-        console.log(chalk.blue('\n' + '─'.repeat(62)));
-        console.log(chalk.bold.white('  Next steps:'));
-        console.log(`  ${chalk.green('aiflow use PROJ-33')}    ${chalk.gray('← load ticket context')}`);
-        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← AI auto-starts analyzing requirement')}`);
-        console.log(chalk.blue('─'.repeat(62)));
-        console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Command list: ${chalk.green('aiflow guide --commands')}`));
-        console.log(chalk.blue('─'.repeat(62)) + '\n');
-    } catch (err) {
-        console.error(chalk.red(`Error during initialization: ${err.message}`));
-    }
-};
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { input } = require('@inquirer/prompts');
+
+const PKG_DIR = path.join(__dirname, '..');
+const PKG_VERSION = require('../package.json').version;
+
+// Map framework → language family for picking the right rules
+const FRAMEWORK_LANGUAGE = {
+    'laravel':      'php',
+    'spring-boot':  'java',
+    'reactjs':      'javascript',
+    'nextjs':       'javascript',
+    'vue-nuxt':     'javascript',
+};
+
+const AI_TOOL_FILES = {
+    'claude':   'CLAUDE.md',
+    'cursor':   '.cursorrules',
+    'gemini':   'GEMINI.md',
+    'copilot':  '.github/copilot-instructions.md',
+    'generic':  'AI_INSTRUCTIONS.md'
+};
+
+/**
+ * Copy documentation files and the docs/ folder to the project
+ */
+async function copyDocsToProject(projectDir) {
+    const aiflowDocsDir = path.join(projectDir, '.aiflow', 'docs');
+    const srcDocsDir = path.join(PKG_DIR, 'docs');
+
+    // 1. Copy the entire docs/ folder to .aiflow/docs
+    if (await fs.pathExists(srcDocsDir)) {
+        await fs.ensureDir(aiflowDocsDir);
+        await fs.copy(srcDocsDir, aiflowDocsDir, { overwrite: true });
+        console.log(chalk.green(`✓ Documentation folder copied to .aiflow/docs`));
+    }
+
+    // 2. Copy key markdown files to project root for easy access
+    const keyFiles = ['QUICK_START.md', 'AIFLOW.md', 'CONTRIBUTING.md'];
+    for (const file of keyFiles) {
+        const srcPath = path.join(PKG_DIR, file);
+        const destPath = path.join(projectDir, file);
+        if (await fs.pathExists(srcPath)) {
+            // We overwrite these to ensure they are up to date with the installed version
+            await fs.copy(srcPath, destPath, { overwrite: true });
+            console.log(chalk.gray(`  ✓ ${file} updated in project root`));
+        }
+    }
+}
+
+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 hookSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
+    const hookDest = path.join(hooksDir, 'session-start.js');
+    await fs.copy(hookSrc, hookDest, { 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 = [];
+
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+        h => !(h._aiflowKit)
+    );
+    settings.hooks.SessionStart.push({
+        _aiflowKit: true,
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookDest.replace(/\\/g, '/')}"`,
+            }
+        ]
+    });
+
+    await fs.writeJson(settingsFile, settings, { spaces: 2 });
+    console.log(chalk.green(`✓ Superpowers SessionStart hook 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 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`;
+
+    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 (workflowContent) {
+            finalContent += workflowContent + '\n\n';
+        }
+
+        finalContent += frameworkContent;
+
+        if (!multi) {
+            await fs.writeFile(targetPath, finalContent);
+        } else {
+            if (await fs.pathExists(targetPath)) {
+                await fs.appendFile(targetPath, separator + frameworkContent);
+            } else {
+                await fs.writeFile(targetPath, finalContent);
+            }
+        }
+    }
+
+    console.log(chalk.green(`✓ AI instruction files updated for framework: ${framework} (${selectedTools.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];
+
+    const credsFile = path.join(projectDir, '.aiflow', 'credentials.json');
+    let existingCreds = {};
+    if (await fs.pathExists(credsFile)) {
+        existingCreds = await fs.readJson(credsFile).catch(() => ({}));
+    }
+
+    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 }
+    );
+
+    Object.assign(existingCreds, credentials);
+    await fs.writeJson(credsFile, existingCreds, { spaces: 2 });
+    await ensureCredentialsGitignored(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: { 'Authorization': `Bearer ${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 ensureCredentialsGitignored(projectDir) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    const entry = '.aiflow/credentials.json';
+    let content = '';
+    if (await fs.pathExists(gitignorePath)) {
+        content = await fs.readFile(gitignorePath, 'utf-8');
+    }
+    const lines = content.split('\n').map(l => l.trim());
+    if (lines.includes(entry)) return;
+    const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+    await fs.appendFile(gitignorePath, `${separator}${entry}\n`);
+    console.log(chalk.yellow(`  ⚠ Added ${entry} to .gitignore (contains API keys)`));
+}
+
+function maskSecret(value) {
+    if (!value || value.length <= 8) return '***';
+    return `${value.slice(0, 4)}***${value.slice(-4)}`;
+}
+
+async function init(options) {
+    const projectDir = process.cwd();
+    const aiflowDir  = path.join(projectDir, '.aiflow');
+    const frameworks = options.frameworks || (options.framework ? [options.framework] : []);
+    const adapters   = options.adapters   || (options.adapter   ? [options.adapter]   : []);
+    const primaryFramework = frameworks[0] || null;
+    const versionDir = path.join(aiflowDir, 'versions', PKG_VERSION);
+
+    try {
+        console.log(chalk.blue(`Initializing ai-flow-kit (v${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);
+        
+        // --- Added: Copy docs to project ---
+        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);
+        }
+
+        console.log(chalk.green('\n✨ Initialized AI Flow Kit successfully!'));
+        console.log(chalk.blue('\n' + '─'.repeat(62)));
+        console.log(chalk.bold.white('  Next steps:'));
+        console.log(`  ${chalk.green('aiflow use PROJ-33')}    ${chalk.gray('← load ticket context')}`);
+        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← Use Claude Code CLI (recommended)')}`);
+        console.log(`  ${chalk.green('Cursor / Gemini')}       ${chalk.gray('← Instructions loaded in .cursorrules / GEMINI.md')}`);
+        console.log(chalk.blue('─'.repeat(62)));
+        console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Command list: ${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;