thachvd-kit 1.0.14 → 1.0.16

package/bin/cli.js

@@ -1,60 +1,60 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const prompts = require('prompts');
-const pc = require('picocolors');
-const packageJson = require('../package.json');
+const fs = require('fs');
+const path = require('path');
+const prompts = require('prompts');
+const pc = require('picocolors');
+const packageJson = require('../package.json');
 
 const sourceDir = path.resolve(__dirname, '..');
 const targetDir = process.cwd();
 
 // --- Skill Resolver ---
 
-const LANG_SKILLS = {
-    javascript: ["nodejs-best-practices", "api-design"],
-    typescript: ["nodejs-best-practices", "api-design"],
-    python: ["python-patterns"],
-    go: ["golang-patterns", "golang-testing"],
-    php: ["api-design"],
-    rust: ["rust-pro"],
-    java: ["api-design"],
-    ruby: ["api-design"],
-    swift: ["mobile-design"],
-    kotlin: ["mobile-design"],
-    csharp: ["api-design"],
-};
-
-const FRAMEWORK_SKILLS = {
-    vue: ["frontend-design", "tailwind-patterns"],
-    react: ["react-frontend", "frontend-design"],
-    next: ["nextjs-react-expert", "frontend-design"],
-    nuxt: ["frontend-design"],
-    svelte: ["frontend-design"],
-    angular: ["frontend-design"],
-    laravel: ["laravel-patterns", "laravel-security", "laravel-tdd"],
-    cakephp: ["api-design"],
-    symfony: ["api-design"],
-    codeigniter: ["api-design"],
-    express: ["nodejs-best-practices", "api-design"],
-    fastapi: ["python-patterns", "api-design"],
-    django: ["python-patterns", "api-design"],
-    flask: ["python-patterns", "api-design"],
-    gin: ["golang-patterns", "golang-testing"],
-    fiber: ["golang-patterns", "golang-testing"],
-    echo: ["golang-patterns", "golang-testing"],
-    nestjs: ["nodejs-best-practices", "api-design"],
-    rails: ["api-design"],
-    spring: ["api-design"],
-    aspnet: ["api-design"],
-    tauri: ["rust-pro", "desktop-design"],
-    axum: ["rust-pro", "api-design"],
-    actix: ["rust-pro", "api-design"],
-    flutter: ["mobile-design"],
-    "react-native": ["mobile-design"],
-};
-
-const INFRA_SKILLS = {
+const LANG_SKILLS = {
+    javascript: ["nodejs-best-practices", "api-design"],
+    typescript: ["nodejs-best-practices", "api-design"],
+    python: ["python-patterns"],
+    go: ["golang-patterns", "golang-testing"],
+    php: ["api-design"],
+    rust: ["rust-pro"],
+    java: ["api-design"],
+    ruby: ["api-design"],
+    swift: ["mobile-design"],
+    kotlin: ["mobile-design"],
+    csharp: ["api-design"],
+};
+
+const FRAMEWORK_SKILLS = {
+    vue: ["frontend-design", "tailwind-patterns"],
+    react: ["react-frontend", "frontend-design"],
+    next: ["nextjs-react-expert", "frontend-design"],
+    nuxt: ["frontend-design"],
+    svelte: ["frontend-design"],
+    angular: ["frontend-design"],
+    laravel: ["laravel-patterns", "laravel-security", "laravel-tdd"],
+    cakephp: ["api-design"],
+    symfony: ["api-design"],
+    codeigniter: ["api-design"],
+    express: ["nodejs-best-practices", "api-design"],
+    fastapi: ["python-patterns", "api-design"],
+    django: ["python-patterns", "api-design"],
+    flask: ["python-patterns", "api-design"],
+    gin: ["golang-patterns", "golang-testing"],
+    fiber: ["golang-patterns", "golang-testing"],
+    echo: ["golang-patterns", "golang-testing"],
+    nestjs: ["nodejs-best-practices", "api-design"],
+    rails: ["api-design"],
+    spring: ["api-design"],
+    aspnet: ["api-design"],
+    tauri: ["rust-pro", "desktop-design"],
+    axum: ["rust-pro", "api-design"],
+    actix: ["rust-pro", "api-design"],
+    flutter: ["mobile-design"],
+    "react-native": ["mobile-design"],
+};
+
+const INFRA_SKILLS = {
     docker: ["docker-patterns"],
     aws: ["deployment-procedures", "docker-patterns"],
     gcp: ["deployment-procedures", "docker-patterns"],
@@ -87,716 +87,723 @@ function resolveSkills(data) {
     skills.add("clean-code");
     skills.add("systematic-debugging");
 
-    return Array.from(skills).sort();
-}
-
-const FRAMEWORK_CHOICES = [
-    'vue', 'react', 'next', 'nuxt', 'svelte', 'angular',
-    'laravel', 'cakephp', 'symfony', 'codeigniter',
-    'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs',
-    'rails', 'spring', 'aspnet',
-    'tauri', 'axum', 'actix', 'flutter', 'react-native'
-];
-
-const LANGUAGE_CHOICES = ['typescript', 'javascript', 'python', 'go', 'php', 'rust', 'java', 'ruby', 'swift', 'kotlin', 'csharp', 'cpp'];
-const PROJECT_TYPE_CHOICES = ['web-app', 'api', 'mobile', 'desktop', 'cli', 'fullstack'];
-const DATABASE_CHOICES = ['postgres', 'mysql', 'sqlite', 'mongodb', 'redis', 'dynamodb', 'none'];
-const PACKAGE_MANAGER_CHOICES = ['npm', 'pnpm', 'yarn', 'bun', 'pip', 'uv', 'go mod', 'cargo', 'composer', 'auto-detect'];
-const TEST_FRAMEWORK_CHOICES = ['jest', 'vitest', 'pytest', 'go test', 'phpunit', 'pest', 'rspec', 'junit', 'auto-detect'];
-const CLOUD_CHOICES = ['aws', 'gcp', 'azure', 'vercel', 'fly', 'railway', 'none'];
-const FRONTEND_FRAMEWORKS = ['vue', 'react', 'next', 'nuxt', 'svelte', 'angular'];
-const BACKEND_FRAMEWORKS = ['laravel', 'cakephp', 'symfony', 'codeigniter', 'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs', 'rails', 'spring', 'aspnet', 'axum', 'actix'];
-const MOBILE_DESKTOP_FRAMEWORKS = ['tauri', 'flutter', 'react-native'];
-const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.next', '.nuxt', '.turbo', '.cache', 'storage', 'tmp']);
-
-function printHelp() {
-    console.log(`
-${pc.bold('Usage:')}
-  thachvd-kit init [--scan] [--yes]
-  thachvd-kit --version
-  thachvd-kit --help
-
-${pc.bold('Commands:')}
-  init      Run the project init wizard
-
-${pc.bold('Options:')}
-  --scan    Scan the current project to prefill PROJECT_CONTEXT.md
-  --yes     Use detected/default values without prompting
-  --version Show the installed CLI version
-  --help    Show this help message
-`);
-}
-
-function formatScanPreviewLines(scanned) {
-    return [
-        ['App root', scanned.app_root || '.'],
-        ['Project type', scanned.project_type || 'unknown'],
-        ['Primary language', scanned.primary_language || 'unknown'],
-        ['Frameworks', (scanned.frameworks || []).join(', ') || 'no framework'],
-        ['Database', scanned.database || 'none'],
-        ['Package manager', scanned.package_manager || 'auto-detect'],
-        ['Test framework', scanned.test_framework || 'auto-detect'],
-        ['Cloud', scanned.cloud || 'none'],
-        ['Infrastructure', (scanned.infrastructure || []).join(', ') || 'none'],
-        ['CI/CD', scanned.ci_cd || 'none']
-    ];
-}
-
-async function askQuestions(questions) {
-    return prompts(questions, {
-        onCancel: () => {
-            console.log(pc.yellow('\nCancelled.'));
-            process.exit(130);
-        }
-    });
-}
-
-function fileExists(...parts) {
-    return fs.existsSync(path.join(targetDir, ...parts));
-}
-
-function fileExistsAt(baseDir, ...parts) {
-    return fs.existsSync(path.join(baseDir, ...parts));
-}
-
-function readJsonIfExists(...parts) {
-    const fullPath = path.join(targetDir, ...parts);
-    if (!fs.existsSync(fullPath)) return null;
-    try {
-        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-    } catch {
-        return null;
-    }
-}
-
-function readJsonIfExistsAt(baseDir, ...parts) {
-    const fullPath = path.join(baseDir, ...parts);
-    if (!fs.existsSync(fullPath)) return null;
-    try {
-        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-    } catch {
-        return null;
-    }
-}
-
-function readTextIfExists(...parts) {
-    const fullPath = path.join(targetDir, ...parts);
-    if (!fs.existsSync(fullPath)) return '';
-    try {
-        return fs.readFileSync(fullPath, 'utf8');
-    } catch {
-        return '';
-    }
-}
-
-function readTextIfExistsAt(baseDir, ...parts) {
-    const fullPath = path.join(baseDir, ...parts);
-    if (!fs.existsSync(fullPath)) return '';
-    try {
-        return fs.readFileSync(fullPath, 'utf8');
-    } catch {
-        return '';
-    }
-}
-
-function detectPackageManager(baseDir = targetDir) {
-    if (fileExistsAt(baseDir, 'pnpm-lock.yaml')) return 'pnpm';
-    if (fileExistsAt(baseDir, 'yarn.lock')) return 'yarn';
-    if (fileExistsAt(baseDir, 'bun.lockb') || fileExistsAt(baseDir, 'bun.lock')) return 'bun';
-    if (fileExistsAt(baseDir, 'package-lock.json')) return 'npm';
-    if (fileExistsAt(baseDir, 'uv.lock')) return 'uv';
-    if (fileExistsAt(baseDir, 'poetry.lock')) return 'pip';
-    if (fileExistsAt(baseDir, 'requirements.txt') || fileExistsAt(baseDir, 'pyproject.toml')) return 'pip';
-    if (fileExistsAt(baseDir, 'go.mod')) return 'go mod';
-    if (fileExistsAt(baseDir, 'Cargo.toml')) return 'cargo';
-    if (fileExistsAt(baseDir, 'composer.json')) return 'composer';
-    return 'auto-detect';
-}
-
-function uniq(values) {
-    return Array.from(new Set(values.filter(Boolean)));
-}
-
-function detectAppRoot(baseDir) {
-    const candidates = [baseDir];
-    const queue = [{ dir: baseDir, depth: 0 }];
-
-    while (queue.length > 0) {
-        const { dir, depth } = queue.shift();
-        if (depth >= 2) continue;
-        let entries = [];
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        } catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory()) continue;
-            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
-            const nextDir = path.join(dir, entry.name);
-            candidates.push(nextDir);
-            queue.push({ dir: nextDir, depth: depth + 1 });
-        }
-    }
-
-    const scoreCandidate = dir => {
-        let score = 0;
-        if (fileExistsAt(dir, 'composer.json')) score += 5;
-        if (fileExistsAt(dir, 'package.json')) score += 4;
-        if (fileExistsAt(dir, 'Cargo.toml')) score += 4;
-        if (fileExistsAt(dir, 'go.mod')) score += 4;
-        if (fileExistsAt(dir, 'pyproject.toml') || fileExistsAt(dir, 'requirements.txt')) score += 4;
-        if (fileExistsAt(dir, 'artisan')) score += 5;
-        if (fileExistsAt(dir, 'bin', 'cake') || fileExistsAt(dir, 'app', 'Config', 'core.php')) score += 5;
-        if (fileExistsAt(dir, 'src-tauri', 'tauri.conf.json') || fileExistsAt(dir, 'src-tauri', 'tauri.conf.json5')) score += 5;
-        if (fileExistsAt(dir, 'manage.py')) score += 4;
-        if (fileExistsAt(dir, 'Gemfile')) score += 4;
-        if (fileExistsAt(dir, 'pom.xml') || fileExistsAt(dir, 'build.gradle') || fileExistsAt(dir, 'build.gradle.kts')) score += 4;
-        if (fileExistsAt(dir, 'app', 'View') || fileExistsAt(dir, 'resources', 'views') || fileExistsAt(dir, 'templates') || fileExistsAt(dir, 'app', 'views')) score += 2;
-        return score;
-    };
-
-    const ranked = candidates
-        .map(dir => ({ dir, score: scoreCandidate(dir) }))
-        .filter(item => item.score > 0)
-        .sort((a, b) => (b.score - a.score) || (a.dir.length - b.dir.length));
-
-    return ranked[0]?.dir || baseDir;
-}
-
-function repoHasAny(baseDir, relativePaths, maxDepth = 3) {
-    const queue = [{ dir: baseDir, depth: 0 }];
-    while (queue.length > 0) {
-        const { dir, depth } = queue.shift();
-        for (const relativePath of relativePaths) {
-            if (fileExistsAt(dir, ...relativePath)) return true;
-        }
-        if (depth >= maxDepth) continue;
-        let entries = [];
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        } catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory()) continue;
-            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
-            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
-        }
-    }
-    return false;
-}
-
-function evidenceIf(condition, label, weight = 1) {
-    return condition ? { label, weight } : null;
-}
-
-function buildDetection(id, evidence, meta = {}) {
-    const hits = evidence.filter(Boolean);
-    const score = hits.reduce((sum, hit) => sum + hit.weight, 0);
-    return {
-        id,
-        score,
-        evidence: hits.map(hit => hit.label),
-        ...meta
-    };
-}
-
-function confidenceLabel(score) {
-    if (score >= 6) return 'high';
-    if (score >= 3) return 'medium';
-    return 'low';
-}
-
-function hasDependency(depNames, ...names) {
-    return names.some(name => depNames.has(name));
-}
-
-function hasComposerDependency(composerDepNames, ...names) {
-    return names.some(name => composerDepNames.has(name));
-}
-
-function hasRootFile(rootEntries, ...filenames) {
-    return filenames.some(name => rootEntries.has(name));
-}
-
-function textMatches(text, pattern) {
-    return Boolean(text && pattern.test(text));
-}
-
-const LANGUAGE_DETECTORS = [
-    {
-        id: 'typescript',
-        detect: ctx => buildDetection('typescript', [
-            evidenceIf(ctx.fileExists('tsconfig.json'), 'found tsconfig.json', 4),
-            evidenceIf(hasDependency(ctx.depNames, 'typescript', 'ts-node', 'tsx'), 'package.json -> typescript toolchain', 2)
-        ])
-    },
-    {
-        id: 'javascript',
-        detect: ctx => buildDetection('javascript', [
-            evidenceIf(ctx.fileExists('package.json'), 'found package.json', 2),
-            evidenceIf(ctx.depNames.size > 0, 'package.json -> JavaScript dependency graph', 1)
-        ])
-    },
-    {
-        id: 'python',
-        detect: ctx => buildDetection('python', [
-            evidenceIf(ctx.fileExists('requirements.txt'), 'found requirements.txt', 3),
-            evidenceIf(ctx.fileExists('pyproject.toml'), 'found pyproject.toml', 2),
-            evidenceIf(textMatches(ctx.pyprojectText, /\[tool\.(poetry|uv|hatch|pdm)\]/i), 'pyproject.toml -> Python tool section', 2)
-        ])
-    },
-    {
-        id: 'go',
-        detect: ctx => buildDetection('go', [
-            evidenceIf(ctx.fileExists('go.mod'), 'found go.mod', 4)
-        ])
-    },
-    {
-        id: 'php',
-        detect: ctx => buildDetection('php', [
-            evidenceIf(ctx.fileExists('composer.json'), 'found composer.json', 4),
-            evidenceIf(ctx.composerDepNames.size > 0, 'composer.json -> PHP dependency graph', 1)
-        ])
-    },
-    {
-        id: 'rust',
-        detect: ctx => buildDetection('rust', [
-            evidenceIf(ctx.fileExists('Cargo.toml'), 'found Cargo.toml', 4),
-            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 5)
-        ])
-    },
-    {
-        id: 'java',
-        detect: ctx => buildDetection('java', [
-            evidenceIf(ctx.fileExists('pom.xml'), 'found pom.xml', 4),
-            evidenceIf(ctx.fileExists('build.gradle') || ctx.fileExists('build.gradle.kts'), 'found Gradle build file', 3)
-        ])
-    },
-    {
-        id: 'ruby',
-        detect: ctx => buildDetection('ruby', [
-            evidenceIf(ctx.fileExists('Gemfile'), 'found Gemfile', 4),
-            evidenceIf(ctx.fileExists('config.ru'), 'found config.ru', 1)
-        ])
-    },
-    {
-        id: 'csharp',
-        detect: ctx => buildDetection('csharp', [
-            evidenceIf(ctx.rootEntries.some(name => name.endsWith('.sln') || name.endsWith('.csproj')), 'found .sln/.csproj', 4),
-            evidenceIf(ctx.fileExists('Program.cs'), 'found Program.cs', 1)
-        ])
-    }
-];
-
-const FRAMEWORK_DETECTORS = [
-    {
-        id: 'next',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('next', [
-            evidenceIf(hasDependency(ctx.depNames, 'next'), 'package.json -> next', 4),
-            evidenceIf(ctx.fileExists('next.config.js') || ctx.fileExists('next.config.mjs') || ctx.fileExists('next.config.ts'), 'found next.config.*', 3),
-            evidenceIf(ctx.fileExists('app') || ctx.fileExists('pages'), 'found app/ or pages/', 1)
-        ])
-    },
-    {
-        id: 'react',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('react', [
-            evidenceIf(hasDependency(ctx.depNames, 'react'), 'package.json -> react', 4),
-            evidenceIf(hasDependency(ctx.depNames, 'react-dom'), 'package.json -> react-dom', 2)
-        ])
-    },
-    {
-        id: 'vue',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('vue', [
-            evidenceIf(hasDependency(ctx.depNames, 'vue'), 'package.json -> vue', 4)
-        ])
-    },
-    {
-        id: 'nuxt',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('nuxt', [
-            evidenceIf(hasDependency(ctx.depNames, 'nuxt'), 'package.json -> nuxt', 4),
-            evidenceIf(ctx.fileExists('nuxt.config.ts') || ctx.fileExists('nuxt.config.js'), 'found nuxt.config.*', 3)
-        ])
-    },
-    {
-        id: 'svelte',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('svelte', [
-            evidenceIf(hasDependency(ctx.depNames, 'svelte', '@sveltejs/kit'), 'package.json -> svelte', 4)
-        ])
-    },
-    {
-        id: 'angular',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('angular', [
-            evidenceIf(hasDependency(ctx.depNames, '@angular/core'), 'package.json -> @angular/core', 4),
-            evidenceIf(ctx.fileExists('angular.json'), 'found angular.json', 3)
-        ])
-    },
-    {
-        id: 'express',
-        kind: 'backend',
-        language: 'javascript',
-        projectType: 'api',
-        detect: ctx => buildDetection('express', [
-            evidenceIf(hasDependency(ctx.depNames, 'express'), 'package.json -> express', 4)
-        ])
-    },
-    {
-        id: 'nestjs',
-        kind: 'backend',
-        language: 'javascript',
-        projectType: 'api',
-        detect: ctx => buildDetection('nestjs', [
-            evidenceIf(hasDependency(ctx.depNames, '@nestjs/core'), 'package.json -> @nestjs/core', 4)
-        ])
-    },
-    {
-        id: 'fastapi',
-        kind: 'backend',
-        language: 'python',
-        projectType: 'api',
-        detect: ctx => buildDetection('fastapi', [
-            evidenceIf(textMatches(ctx.requirementsText, /\bfastapi\b/i) || textMatches(ctx.pyprojectText, /\bfastapi\b/i), 'Python deps -> fastapi', 4)
-        ])
-    },
-    {
-        id: 'django',
-        kind: 'backend',
-        language: 'python',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('django', [
-            evidenceIf(textMatches(ctx.requirementsText, /\bdjango\b/i) || textMatches(ctx.pyprojectText, /\bdjango\b/i), 'Python deps -> django', 4),
-            evidenceIf(ctx.fileExists('manage.py'), 'found manage.py', 2),
-            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
-        ])
-    },
-    {
-        id: 'flask',
-        kind: 'backend',
-        language: 'python',
-        projectType: 'api',
-        detect: ctx => buildDetection('flask', [
-            evidenceIf(textMatches(ctx.requirementsText, /\bflask\b/i) || textMatches(ctx.pyprojectText, /\bflask\b/i), 'Python deps -> flask', 4)
-        ])
-    },
-    {
-        id: 'laravel',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('laravel', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'laravel/framework'), 'composer.json -> laravel/framework', 4),
-            evidenceIf(ctx.fileExists('artisan'), 'found artisan', 3),
-            evidenceIf(ctx.fileExists('resources', 'views'), 'found resources/views', 1)
-        ])
-    },
-    {
-        id: 'cakephp',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('cakephp', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'cakephp/cakephp'), 'composer.json -> cakephp/cakephp', 4),
-            evidenceIf(ctx.fileExists('bin', 'cake'), 'found bin/cake', 3),
-            evidenceIf(ctx.fileExists('config', 'app.php'), 'found config/app.php', 2),
-            evidenceIf(ctx.fileExists('app', 'Config', 'core.php'), 'found app/Config/core.php (CakePHP legacy)', 3),
-            evidenceIf(ctx.fileExists('app', 'Controller', 'AppController.php'), 'found app/Controller/AppController.php', 2),
-            evidenceIf(ctx.fileExists('app', 'Model', 'AppModel.php'), 'found app/Model/AppModel.php', 2),
-            evidenceIf(ctx.fileExists('lib', 'Cake'), 'found lib/Cake', 3),
-            evidenceIf(ctx.fileExists('cake', 'console', 'cake'), 'found cake/console/cake', 3),
-            evidenceIf(ctx.fileExists('app', 'View'), 'found app/View', 2),
-            evidenceIf(textMatches(ctx.viewFilesText, /\.ctp$/im), 'found .ctp view templates', 2)
-        ])
-    },
-    {
-        id: 'symfony',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('symfony', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'symfony/framework-bundle'), 'composer.json -> symfony/framework-bundle', 4),
-            evidenceIf(ctx.fileExists('bin', 'console'), 'found bin/console', 2),
-            evidenceIf(ctx.fileExists('config', 'bundles.php'), 'found config/bundles.php', 1),
-            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
-        ])
-    },
-    {
-        id: 'codeigniter',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'api',
-        detect: ctx => buildDetection('codeigniter', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'codeigniter4/framework'), 'composer.json -> codeigniter4/framework', 4),
-            evidenceIf(ctx.fileExists('spark'), 'found spark', 2),
-            evidenceIf(ctx.fileExists('app', 'Config', 'App.php'), 'found app/Config/App.php', 1)
-        ])
-    },
-    {
-        id: 'gin',
-        kind: 'backend',
-        language: 'go',
-        projectType: 'api',
-        detect: ctx => buildDetection('gin', [
-            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gin-gonic\/gin\b/i), 'go.mod -> github.com/gin-gonic/gin', 4)
-        ])
-    },
-    {
-        id: 'fiber',
-        kind: 'backend',
-        language: 'go',
-        projectType: 'api',
-        detect: ctx => buildDetection('fiber', [
-            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gofiber\/fiber\b/i), 'go.mod -> github.com/gofiber/fiber', 4)
-        ])
-    },
-    {
-        id: 'echo',
-        kind: 'backend',
-        language: 'go',
-        projectType: 'api',
-        detect: ctx => buildDetection('echo', [
-            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/labstack\/echo\b/i), 'go.mod -> github.com/labstack/echo', 4)
-        ])
-    },
-    {
-        id: 'rails',
-        kind: 'backend',
-        language: 'ruby',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('rails', [
-            evidenceIf(textMatches(ctx.gemfileText, /^\s*gem\s+["']rails["']/im), 'Gemfile -> rails', 4),
-            evidenceIf(ctx.fileExists('bin', 'rails'), 'found bin/rails', 2),
-            evidenceIf(ctx.fileExists('app', 'views'), 'found app/views', 1)
-        ])
-    },
-    {
-        id: 'spring',
-        kind: 'backend',
-        language: 'java',
-        projectType: 'api',
-        detect: ctx => buildDetection('spring', [
-            evidenceIf(textMatches(ctx.pomText, /spring-boot/i) || textMatches(ctx.gradleText, /spring-boot/i), 'Java build -> spring-boot', 4)
-        ])
-    },
-    {
-        id: 'aspnet',
-        kind: 'backend',
-        language: 'csharp',
-        projectType: 'api',
-        detect: ctx => buildDetection('aspnet', [
-            evidenceIf(textMatches(ctx.csprojText, /Microsoft\.NET\.Sdk\.Web/i), '.csproj -> Microsoft.NET.Sdk.Web', 4),
-            evidenceIf(textMatches(ctx.programCsText, /WebApplication\.CreateBuilder/i), 'Program.cs -> WebApplication.CreateBuilder', 2)
-        ])
-    },
-    {
-        id: 'tauri',
-        kind: 'desktop',
-        language: 'rust',
-        projectType: 'desktop',
-        detect: ctx => buildDetection('tauri', [
-            evidenceIf(hasDependency(ctx.depNames, '@tauri-apps/api'), 'package.json -> @tauri-apps/api', 4),
-            evidenceIf(ctx.fileExists('src-tauri', 'tauri.conf.json') || ctx.fileExists('src-tauri', 'tauri.conf.json5'), 'found src-tauri/tauri.conf.*', 4),
-            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 2)
-        ])
-    },
-    {
-        id: 'axum',
-        kind: 'backend',
-        language: 'rust',
-        projectType: 'api',
-        detect: ctx => buildDetection('axum', [
-            evidenceIf(textMatches(ctx.cargoText, /\baxum\b/i), 'Cargo.toml -> axum', 4)
-        ])
-    },
-    {
-        id: 'actix',
-        kind: 'backend',
-        language: 'rust',
-        projectType: 'api',
-        detect: ctx => buildDetection('actix', [
-            evidenceIf(textMatches(ctx.cargoText, /\bactix-web\b/i), 'Cargo.toml -> actix-web', 4)
-        ])
-    },
-    {
-        id: 'flutter',
-        kind: 'mobile',
-        projectType: 'mobile',
-        detect: ctx => buildDetection('flutter', [
-            evidenceIf(textMatches(ctx.pubspecText, /^\s*flutter\s*:/im), 'pubspec.yaml -> flutter', 4)
-        ])
-    },
-    {
-        id: 'react-native',
-        kind: 'mobile',
-        projectType: 'mobile',
-        detect: ctx => buildDetection('react-native', [
-            evidenceIf(hasDependency(ctx.depNames, 'react-native', 'expo'), 'package.json -> react-native/expo', 4)
-        ])
-    }
-];
-
-function scanProject() {
-    const appRoot = detectAppRoot(targetDir);
-    const pkg = readJsonIfExistsAt(appRoot, 'package.json') || {};
-    const composer = readJsonIfExistsAt(appRoot, 'composer.json') || {};
-    const rootEntries = fs.existsSync(appRoot) ? fs.readdirSync(appRoot) : [];
-    const rootCsproj = rootEntries.find(name => name.endsWith('.csproj')) || '';
-    const deps = {
-        ...(pkg.dependencies || {}),
-        ...(pkg.devDependencies || {}),
-        ...(pkg.peerDependencies || {})
-    };
-    const depNames = new Set(Object.keys(deps));
-    const composerDeps = {
-        ...(composer.require || {}),
-        ...(composer['require-dev'] || {})
-    };
-    const composerDepNames = new Set(Object.keys(composerDeps));
-    const ctx = {
-        pkg,
-        composer,
-        depNames,
-        composerDepNames,
-        rootEntries,
-        fileExists: (...parts) => fileExistsAt(appRoot, ...parts),
-        requirementsText: readTextIfExistsAt(appRoot, 'requirements.txt'),
-        pyprojectText: readTextIfExistsAt(appRoot, 'pyproject.toml'),
-        goModText: readTextIfExistsAt(appRoot, 'go.mod'),
-        pubspecText: readTextIfExistsAt(appRoot, 'pubspec.yaml'),
-        gemfileText: readTextIfExistsAt(appRoot, 'Gemfile'),
-        pomText: readTextIfExistsAt(appRoot, 'pom.xml'),
-        gradleText: `${readTextIfExistsAt(appRoot, 'build.gradle')}\n${readTextIfExistsAt(appRoot, 'build.gradle.kts')}`,
-        cargoText: `${readTextIfExistsAt(appRoot, 'Cargo.toml')}\n${readTextIfExistsAt(appRoot, 'src-tauri', 'Cargo.toml')}`,
-        csprojText: rootCsproj ? readTextIfExistsAt(appRoot, rootCsproj) : '',
-        programCsText: readTextIfExistsAt(appRoot, 'Program.cs'),
-        viewFilesText: fs.existsSync(path.join(appRoot, 'app', 'View'))
-            ? fs.readdirSync(path.join(appRoot, 'app', 'View'), { recursive: true }).join('\n')
-            : ''
-    };
-
-    const languageDetections = LANGUAGE_DETECTORS
-        .map(detector => detector.detect(ctx))
-        .filter(result => result.score >= 2)
-        .sort((a, b) => b.score - a.score);
-
-    const frameworkDetails = FRAMEWORK_DETECTORS
-        .map(detector => {
-            const result = detector.detect(ctx);
-            if (result.score < 3) return null;
-            return {
-                ...result,
-                kind: detector.kind,
-                language: detector.language,
-                projectType: detector.projectType,
-                confidence: confidenceLabel(result.score)
-            };
-        })
-        .filter(Boolean)
-        .sort((a, b) => b.score - a.score);
-
-    const frameworkLanguageScores = frameworkDetails.reduce((acc, item) => {
-        if (!item.language) return acc;
-        acc[item.language] = (acc[item.language] || 0) + item.score;
-        return acc;
-    }, {});
-    const primaryLanguage = Object.keys(frameworkLanguageScores).sort((a, b) => frameworkLanguageScores[b] - frameworkLanguageScores[a])[0]
-        || languageDetections[0]?.id
-        || 'typescript';
-    const frameworks = uniq(frameworkDetails.map(item => item.id)).filter(name => FRAMEWORK_CHOICES.includes(name));
-    const infrastructure = [];
-    let projectType = '';
-    let database = 'none';
-    let testFramework = 'auto-detect';
-    let cloud = 'none';
-    let ciCd = 'none';
-
-    if (frameworkDetails.some(item => item.projectType === 'desktop')) projectType = 'desktop';
-    else if (frameworkDetails.some(item => item.projectType === 'mobile')) projectType = 'mobile';
-    else if (frameworkDetails.some(item => item.kind === 'frontend') && frameworkDetails.some(item => item.kind === 'backend')) projectType = 'fullstack';
-    else if (frameworkDetails.some(item => item.projectType === 'web-app')) projectType = 'web-app';
-    else if (frameworkDetails.some(item => item.kind === 'backend')) projectType = 'api';
-    else if (frameworkDetails.some(item => item.kind === 'frontend')) projectType = 'web-app';
-    else if (fileExistsAt(appRoot, 'package.json') && pkg.bin) projectType = 'cli';
-    else if (['php', 'python', 'go', 'java', 'ruby', 'csharp', 'rust'].includes(primaryLanguage)) projectType = 'api';
-
-    if (hasDependency(depNames, 'pg', 'postgres', '@prisma/client') || /postgres/i.test(JSON.stringify(pkg))) database = 'postgres';
-    else if (hasDependency(depNames, 'mysql', 'mysql2')) database = 'mysql';
-    else if (hasDependency(depNames, 'sqlite3', 'better-sqlite3', 'rusqlite')) database = 'sqlite';
-    else if (hasDependency(depNames, 'mongodb', 'mongoose')) database = 'mongodb';
-    else if (hasDependency(depNames, 'redis', 'ioredis')) database = 'redis';
-    else if (hasDependency(depNames, '@aws-sdk/client-dynamodb')) database = 'dynamodb';
-
-    if (hasDependency(depNames, 'vitest')) testFramework = 'vitest';
-    else if (hasDependency(depNames, 'jest')) testFramework = 'jest';
-    else if (hasDependency(depNames, 'pytest') || textMatches(ctx.requirementsText, /\bpytest\b/i) || textMatches(ctx.pyprojectText, /\bpytest\b/i)) testFramework = 'pytest';
-    else if (hasComposerDependency(composerDepNames, 'phpunit/phpunit')) testFramework = 'phpunit';
-    else if (hasComposerDependency(composerDepNames, 'pestphp/pest')) testFramework = 'pest';
-    else if (fileExistsAt(appRoot, 'go.mod')) testFramework = 'go test';
-    else if (textMatches(ctx.gemfileText, /^\s*gem\s+["']rspec["']/im)) testFramework = 'rspec';
-
-    if (repoHasAny(targetDir, [['Dockerfile'], ['docker-compose.yml'], ['docker-compose.yaml']])) {
-        infrastructure.push('docker');
-    }
-
-    if (repoHasAny(targetDir, [['vercel.json']])) {
-        cloud = 'vercel';
-        infrastructure.push('vercel');
-    } else if (repoHasAny(targetDir, [['fly.toml']])) {
-        cloud = 'fly';
-        infrastructure.push('fly');
-    } else if (repoHasAny(targetDir, [['railway.json'], ['railway.toml']])) {
-        cloud = 'railway';
-        infrastructure.push('railway');
-    }
-
-    if (repoHasAny(targetDir, [['.github', 'workflows'], ['.gitlab-ci.yml'], ['.circleci', 'config.yml'], ['Jenkinsfile']], 2)) {
-        if (repoHasAny(targetDir, [['.github', 'workflows']], 2)) ciCd = 'github-actions';
-        else if (repoHasAny(targetDir, [['.gitlab-ci.yml']], 2)) ciCd = 'gitlab-ci';
-        else if (repoHasAny(targetDir, [['.circleci', 'config.yml']], 2)) ciCd = 'circleci';
-        else if (repoHasAny(targetDir, [['Jenkinsfile']], 2)) ciCd = 'jenkins';
-    }
-
-    const scanEvidence = [
-        ...(languageDetections[0] ? [`language:${languageDetections[0].id} => ${languageDetections[0].evidence.join('; ')}`] : []),
-        ...frameworkDetails.map(item => `${item.id} [${item.confidence}] => ${item.evidence.join('; ')}`)
-    ];
-
-    return {
-        project_name: path.basename(targetDir),
-        app_root: path.relative(targetDir, appRoot) || '.',
-        description: pkg.description || composer.description || 'A software project',
-        project_type: PROJECT_TYPE_CHOICES.includes(projectType) ? projectType : 'web-app',
-        primary_language: LANGUAGE_CHOICES.includes(primaryLanguage) ? primaryLanguage : 'typescript',
-        frameworks,
-        framework_details: frameworkDetails,
-        scan_evidence: scanEvidence,
-        database: DATABASE_CHOICES.includes(database) ? database : 'none',
-        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager(appRoot)) ? detectPackageManager(appRoot) : 'auto-detect',
-        uses_docker: infrastructure.includes('docker'),
-        cloud,
-        infrastructure: uniq(infrastructure),
-        ci_cd: ciCd,
-        test_framework: TEST_FRAMEWORK_CHOICES.includes(testFramework) ? testFramework : 'auto-detect',
-        max_file_lines: '300',
-        code_style: 'project-standard',
-        architecture_notes: '<!-- Add notes -->',
-        current_phase: 'Initial setup',
-        next_phase: '—',
-        known_issues: '<!-- None yet -->'
-    };
-}
+    return Array.from(skills).sort();
+}
+
+const FRAMEWORK_CHOICES = [
+    'vue', 'react', 'next', 'nuxt', 'svelte', 'angular',
+    'laravel', 'cakephp', 'symfony', 'codeigniter',
+    'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs',
+    'rails', 'spring', 'aspnet',
+    'tauri', 'axum', 'actix', 'flutter', 'react-native'
+];
+
+const LANGUAGE_CHOICES = ['typescript', 'javascript', 'python', 'go', 'php', 'rust', 'java', 'ruby', 'swift', 'kotlin', 'csharp', 'cpp'];
+const PROJECT_TYPE_CHOICES = ['web-app', 'api', 'mobile', 'desktop', 'cli', 'fullstack'];
+const DATABASE_CHOICES = ['postgres', 'mysql', 'sqlite', 'mongodb', 'redis', 'dynamodb', 'none'];
+const PACKAGE_MANAGER_CHOICES = ['npm', 'pnpm', 'yarn', 'bun', 'pip', 'uv', 'go mod', 'cargo', 'composer', 'auto-detect'];
+const TEST_FRAMEWORK_CHOICES = ['jest', 'vitest', 'pytest', 'go test', 'phpunit', 'pest', 'rspec', 'junit', 'auto-detect'];
+const CLOUD_CHOICES = ['aws', 'gcp', 'azure', 'vercel', 'fly', 'railway', 'none'];
+const FRONTEND_FRAMEWORKS = ['vue', 'react', 'next', 'nuxt', 'svelte', 'angular'];
+const BACKEND_FRAMEWORKS = ['laravel', 'cakephp', 'symfony', 'codeigniter', 'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs', 'rails', 'spring', 'aspnet', 'axum', 'actix'];
+const MOBILE_DESKTOP_FRAMEWORKS = ['tauri', 'flutter', 'react-native'];
+const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.next', '.nuxt', '.turbo', '.cache', 'storage', 'tmp']);
+
+function printHelp() {
+    console.log(`
+${pc.bold('Usage:')}
+  thachvd-kit init [--scan] [--yes]
+  thachvd-kit --version
+  thachvd-kit --help
+
+${pc.bold('Commands:')}
+  init      Run the project init wizard
+
+${pc.bold('Options:')}
+  --scan    Scan the current project to auto-detect stack
+  --yes     Use detected/default values without prompting
+  --version Show the installed CLI version
+  --help    Show this help message
+
+${pc.bold('What gets generated:')}
+  AGENTS.md   Shared instructions for Codex, Antigravity, and Claude Code
+  CLAUDE.md   Claude Code entry file that imports AGENTS.md
+  GEMINI.md   Antigravity entry file that points to AGENTS.md
+  .agent/     Shared docs, skills, workflows, agents, and rules
+`);
+
+}
+
+function formatScanPreviewLines(scanned) {
+    return [
+        ['App root', scanned.app_root || '.'],
+        ['Project type', scanned.project_type || 'unknown'],
+        ['Primary language', scanned.primary_language || 'unknown'],
+        ['Frameworks', (scanned.frameworks || []).join(', ') || 'no framework'],
+        ['Database', scanned.database || 'none'],
+        ['Package manager', scanned.package_manager || 'auto-detect'],
+        ['Test framework', scanned.test_framework || 'auto-detect'],
+        ['Cloud', scanned.cloud || 'none'],
+        ['Infrastructure', (scanned.infrastructure || []).join(', ') || 'none'],
+        ['CI/CD', scanned.ci_cd || 'none']
+    ];
+}
+
+async function askQuestions(questions) {
+    return prompts(questions, {
+        onCancel: () => {
+            console.log(pc.yellow('\nCancelled.'));
+            process.exit(130);
+        }
+    });
+}
+
+function fileExists(...parts) {
+    return fs.existsSync(path.join(targetDir, ...parts));
+}
+
+function fileExistsAt(baseDir, ...parts) {
+    return fs.existsSync(path.join(baseDir, ...parts));
+}
+
+function readJsonIfExists(...parts) {
+    const fullPath = path.join(targetDir, ...parts);
+    if (!fs.existsSync(fullPath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function readJsonIfExistsAt(baseDir, ...parts) {
+    const fullPath = path.join(baseDir, ...parts);
+    if (!fs.existsSync(fullPath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function readTextIfExists(...parts) {
+    const fullPath = path.join(targetDir, ...parts);
+    if (!fs.existsSync(fullPath)) return '';
+    try {
+        return fs.readFileSync(fullPath, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+function readTextIfExistsAt(baseDir, ...parts) {
+    const fullPath = path.join(baseDir, ...parts);
+    if (!fs.existsSync(fullPath)) return '';
+    try {
+        return fs.readFileSync(fullPath, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+function detectPackageManager(baseDir = targetDir) {
+    if (fileExistsAt(baseDir, 'pnpm-lock.yaml')) return 'pnpm';
+    if (fileExistsAt(baseDir, 'yarn.lock')) return 'yarn';
+    if (fileExistsAt(baseDir, 'bun.lockb') || fileExistsAt(baseDir, 'bun.lock')) return 'bun';
+    if (fileExistsAt(baseDir, 'package-lock.json')) return 'npm';
+    if (fileExistsAt(baseDir, 'uv.lock')) return 'uv';
+    if (fileExistsAt(baseDir, 'poetry.lock')) return 'pip';
+    if (fileExistsAt(baseDir, 'requirements.txt') || fileExistsAt(baseDir, 'pyproject.toml')) return 'pip';
+    if (fileExistsAt(baseDir, 'go.mod')) return 'go mod';
+    if (fileExistsAt(baseDir, 'Cargo.toml')) return 'cargo';
+    if (fileExistsAt(baseDir, 'composer.json')) return 'composer';
+    return 'auto-detect';
+}
+
+function uniq(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+
+function detectAppRoot(baseDir) {
+    const candidates = [baseDir];
+    const queue = [{ dir: baseDir, depth: 0 }];
+
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        if (depth >= 2) continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+            const nextDir = path.join(dir, entry.name);
+            candidates.push(nextDir);
+            queue.push({ dir: nextDir, depth: depth + 1 });
+        }
+    }
+
+    const scoreCandidate = dir => {
+        let score = 0;
+        if (fileExistsAt(dir, 'composer.json')) score += 5;
+        if (fileExistsAt(dir, 'package.json')) score += 4;
+        if (fileExistsAt(dir, 'Cargo.toml')) score += 4;
+        if (fileExistsAt(dir, 'go.mod')) score += 4;
+        if (fileExistsAt(dir, 'pyproject.toml') || fileExistsAt(dir, 'requirements.txt')) score += 4;
+        if (fileExistsAt(dir, 'artisan')) score += 5;
+        if (fileExistsAt(dir, 'bin', 'cake') || fileExistsAt(dir, 'app', 'Config', 'core.php')) score += 5;
+        if (fileExistsAt(dir, 'src-tauri', 'tauri.conf.json') || fileExistsAt(dir, 'src-tauri', 'tauri.conf.json5')) score += 5;
+        if (fileExistsAt(dir, 'manage.py')) score += 4;
+        if (fileExistsAt(dir, 'Gemfile')) score += 4;
+        if (fileExistsAt(dir, 'pom.xml') || fileExistsAt(dir, 'build.gradle') || fileExistsAt(dir, 'build.gradle.kts')) score += 4;
+        if (fileExistsAt(dir, 'app', 'View') || fileExistsAt(dir, 'resources', 'views') || fileExistsAt(dir, 'templates') || fileExistsAt(dir, 'app', 'views')) score += 2;
+        return score;
+    };
+
+    const ranked = candidates
+        .map(dir => ({ dir, score: scoreCandidate(dir) }))
+        .filter(item => item.score > 0)
+        .sort((a, b) => (b.score - a.score) || (a.dir.length - b.dir.length));
+
+    return ranked[0]?.dir || baseDir;
+}
+
+function repoHasAny(baseDir, relativePaths, maxDepth = 3) {
+    const queue = [{ dir: baseDir, depth: 0 }];
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        for (const relativePath of relativePaths) {
+            if (fileExistsAt(dir, ...relativePath)) return true;
+        }
+        if (depth >= maxDepth) continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+    }
+    return false;
+}
+
+function evidenceIf(condition, label, weight = 1) {
+    return condition ? { label, weight } : null;
+}
+
+function buildDetection(id, evidence, meta = {}) {
+    const hits = evidence.filter(Boolean);
+    const score = hits.reduce((sum, hit) => sum + hit.weight, 0);
+    return {
+        id,
+        score,
+        evidence: hits.map(hit => hit.label),
+        ...meta
+    };
+}
+
+function confidenceLabel(score) {
+    if (score >= 6) return 'high';
+    if (score >= 3) return 'medium';
+    return 'low';
+}
+
+function hasDependency(depNames, ...names) {
+    return names.some(name => depNames.has(name));
+}
+
+function hasComposerDependency(composerDepNames, ...names) {
+    return names.some(name => composerDepNames.has(name));
+}
+
+function hasRootFile(rootEntries, ...filenames) {
+    return filenames.some(name => rootEntries.has(name));
+}
+
+function textMatches(text, pattern) {
+    return Boolean(text && pattern.test(text));
+}
+
+const LANGUAGE_DETECTORS = [
+    {
+        id: 'typescript',
+        detect: ctx => buildDetection('typescript', [
+            evidenceIf(ctx.fileExists('tsconfig.json'), 'found tsconfig.json', 4),
+            evidenceIf(hasDependency(ctx.depNames, 'typescript', 'ts-node', 'tsx'), 'package.json -> typescript toolchain', 2)
+        ])
+    },
+    {
+        id: 'javascript',
+        detect: ctx => buildDetection('javascript', [
+            evidenceIf(ctx.fileExists('package.json'), 'found package.json', 2),
+            evidenceIf(ctx.depNames.size > 0, 'package.json -> JavaScript dependency graph', 1)
+        ])
+    },
+    {
+        id: 'python',
+        detect: ctx => buildDetection('python', [
+            evidenceIf(ctx.fileExists('requirements.txt'), 'found requirements.txt', 3),
+            evidenceIf(ctx.fileExists('pyproject.toml'), 'found pyproject.toml', 2),
+            evidenceIf(textMatches(ctx.pyprojectText, /\[tool\.(poetry|uv|hatch|pdm)\]/i), 'pyproject.toml -> Python tool section', 2)
+        ])
+    },
+    {
+        id: 'go',
+        detect: ctx => buildDetection('go', [
+            evidenceIf(ctx.fileExists('go.mod'), 'found go.mod', 4)
+        ])
+    },
+    {
+        id: 'php',
+        detect: ctx => buildDetection('php', [
+            evidenceIf(ctx.fileExists('composer.json'), 'found composer.json', 4),
+            evidenceIf(ctx.composerDepNames.size > 0, 'composer.json -> PHP dependency graph', 1)
+        ])
+    },
+    {
+        id: 'rust',
+        detect: ctx => buildDetection('rust', [
+            evidenceIf(ctx.fileExists('Cargo.toml'), 'found Cargo.toml', 4),
+            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 5)
+        ])
+    },
+    {
+        id: 'java',
+        detect: ctx => buildDetection('java', [
+            evidenceIf(ctx.fileExists('pom.xml'), 'found pom.xml', 4),
+            evidenceIf(ctx.fileExists('build.gradle') || ctx.fileExists('build.gradle.kts'), 'found Gradle build file', 3)
+        ])
+    },
+    {
+        id: 'ruby',
+        detect: ctx => buildDetection('ruby', [
+            evidenceIf(ctx.fileExists('Gemfile'), 'found Gemfile', 4),
+            evidenceIf(ctx.fileExists('config.ru'), 'found config.ru', 1)
+        ])
+    },
+    {
+        id: 'csharp',
+        detect: ctx => buildDetection('csharp', [
+            evidenceIf(ctx.rootEntries.some(name => name.endsWith('.sln') || name.endsWith('.csproj')), 'found .sln/.csproj', 4),
+            evidenceIf(ctx.fileExists('Program.cs'), 'found Program.cs', 1)
+        ])
+    }
+];
+
+const FRAMEWORK_DETECTORS = [
+    {
+        id: 'next',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('next', [
+            evidenceIf(hasDependency(ctx.depNames, 'next'), 'package.json -> next', 4),
+            evidenceIf(ctx.fileExists('next.config.js') || ctx.fileExists('next.config.mjs') || ctx.fileExists('next.config.ts'), 'found next.config.*', 3),
+            evidenceIf(ctx.fileExists('app') || ctx.fileExists('pages'), 'found app/ or pages/', 1)
+        ])
+    },
+    {
+        id: 'react',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('react', [
+            evidenceIf(hasDependency(ctx.depNames, 'react'), 'package.json -> react', 4),
+            evidenceIf(hasDependency(ctx.depNames, 'react-dom'), 'package.json -> react-dom', 2)
+        ])
+    },
+    {
+        id: 'vue',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('vue', [
+            evidenceIf(hasDependency(ctx.depNames, 'vue'), 'package.json -> vue', 4)
+        ])
+    },
+    {
+        id: 'nuxt',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('nuxt', [
+            evidenceIf(hasDependency(ctx.depNames, 'nuxt'), 'package.json -> nuxt', 4),
+            evidenceIf(ctx.fileExists('nuxt.config.ts') || ctx.fileExists('nuxt.config.js'), 'found nuxt.config.*', 3)
+        ])
+    },
+    {
+        id: 'svelte',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('svelte', [
+            evidenceIf(hasDependency(ctx.depNames, 'svelte', '@sveltejs/kit'), 'package.json -> svelte', 4)
+        ])
+    },
+    {
+        id: 'angular',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('angular', [
+            evidenceIf(hasDependency(ctx.depNames, '@angular/core'), 'package.json -> @angular/core', 4),
+            evidenceIf(ctx.fileExists('angular.json'), 'found angular.json', 3)
+        ])
+    },
+    {
+        id: 'express',
+        kind: 'backend',
+        language: 'javascript',
+        projectType: 'api',
+        detect: ctx => buildDetection('express', [
+            evidenceIf(hasDependency(ctx.depNames, 'express'), 'package.json -> express', 4)
+        ])
+    },
+    {
+        id: 'nestjs',
+        kind: 'backend',
+        language: 'javascript',
+        projectType: 'api',
+        detect: ctx => buildDetection('nestjs', [
+            evidenceIf(hasDependency(ctx.depNames, '@nestjs/core'), 'package.json -> @nestjs/core', 4)
+        ])
+    },
+    {
+        id: 'fastapi',
+        kind: 'backend',
+        language: 'python',
+        projectType: 'api',
+        detect: ctx => buildDetection('fastapi', [
+            evidenceIf(textMatches(ctx.requirementsText, /\bfastapi\b/i) || textMatches(ctx.pyprojectText, /\bfastapi\b/i), 'Python deps -> fastapi', 4)
+        ])
+    },
+    {
+        id: 'django',
+        kind: 'backend',
+        language: 'python',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('django', [
+            evidenceIf(textMatches(ctx.requirementsText, /\bdjango\b/i) || textMatches(ctx.pyprojectText, /\bdjango\b/i), 'Python deps -> django', 4),
+            evidenceIf(ctx.fileExists('manage.py'), 'found manage.py', 2),
+            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
+        ])
+    },
+    {
+        id: 'flask',
+        kind: 'backend',
+        language: 'python',
+        projectType: 'api',
+        detect: ctx => buildDetection('flask', [
+            evidenceIf(textMatches(ctx.requirementsText, /\bflask\b/i) || textMatches(ctx.pyprojectText, /\bflask\b/i), 'Python deps -> flask', 4)
+        ])
+    },
+    {
+        id: 'laravel',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('laravel', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'laravel/framework'), 'composer.json -> laravel/framework', 4),
+            evidenceIf(ctx.fileExists('artisan'), 'found artisan', 3),
+            evidenceIf(ctx.fileExists('resources', 'views'), 'found resources/views', 1)
+        ])
+    },
+    {
+        id: 'cakephp',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('cakephp', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'cakephp/cakephp'), 'composer.json -> cakephp/cakephp', 4),
+            evidenceIf(ctx.fileExists('bin', 'cake'), 'found bin/cake', 3),
+            evidenceIf(ctx.fileExists('config', 'app.php'), 'found config/app.php', 2),
+            evidenceIf(ctx.fileExists('app', 'Config', 'core.php'), 'found app/Config/core.php (CakePHP legacy)', 3),
+            evidenceIf(ctx.fileExists('app', 'Controller', 'AppController.php'), 'found app/Controller/AppController.php', 2),
+            evidenceIf(ctx.fileExists('app', 'Model', 'AppModel.php'), 'found app/Model/AppModel.php', 2),
+            evidenceIf(ctx.fileExists('lib', 'Cake'), 'found lib/Cake', 3),
+            evidenceIf(ctx.fileExists('cake', 'console', 'cake'), 'found cake/console/cake', 3),
+            evidenceIf(ctx.fileExists('app', 'View'), 'found app/View', 2),
+            evidenceIf(textMatches(ctx.viewFilesText, /\.ctp$/im), 'found .ctp view templates', 2)
+        ])
+    },
+    {
+        id: 'symfony',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('symfony', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'symfony/framework-bundle'), 'composer.json -> symfony/framework-bundle', 4),
+            evidenceIf(ctx.fileExists('bin', 'console'), 'found bin/console', 2),
+            evidenceIf(ctx.fileExists('config', 'bundles.php'), 'found config/bundles.php', 1),
+            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
+        ])
+    },
+    {
+        id: 'codeigniter',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'api',
+        detect: ctx => buildDetection('codeigniter', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'codeigniter4/framework'), 'composer.json -> codeigniter4/framework', 4),
+            evidenceIf(ctx.fileExists('spark'), 'found spark', 2),
+            evidenceIf(ctx.fileExists('app', 'Config', 'App.php'), 'found app/Config/App.php', 1)
+        ])
+    },
+    {
+        id: 'gin',
+        kind: 'backend',
+        language: 'go',
+        projectType: 'api',
+        detect: ctx => buildDetection('gin', [
+            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gin-gonic\/gin\b/i), 'go.mod -> github.com/gin-gonic/gin', 4)
+        ])
+    },
+    {
+        id: 'fiber',
+        kind: 'backend',
+        language: 'go',
+        projectType: 'api',
+        detect: ctx => buildDetection('fiber', [
+            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gofiber\/fiber\b/i), 'go.mod -> github.com/gofiber/fiber', 4)
+        ])
+    },
+    {
+        id: 'echo',
+        kind: 'backend',
+        language: 'go',
+        projectType: 'api',
+        detect: ctx => buildDetection('echo', [
+            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/labstack\/echo\b/i), 'go.mod -> github.com/labstack/echo', 4)
+        ])
+    },
+    {
+        id: 'rails',
+        kind: 'backend',
+        language: 'ruby',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('rails', [
+            evidenceIf(textMatches(ctx.gemfileText, /^\s*gem\s+["']rails["']/im), 'Gemfile -> rails', 4),
+            evidenceIf(ctx.fileExists('bin', 'rails'), 'found bin/rails', 2),
+            evidenceIf(ctx.fileExists('app', 'views'), 'found app/views', 1)
+        ])
+    },
+    {
+        id: 'spring',
+        kind: 'backend',
+        language: 'java',
+        projectType: 'api',
+        detect: ctx => buildDetection('spring', [
+            evidenceIf(textMatches(ctx.pomText, /spring-boot/i) || textMatches(ctx.gradleText, /spring-boot/i), 'Java build -> spring-boot', 4)
+        ])
+    },
+    {
+        id: 'aspnet',
+        kind: 'backend',
+        language: 'csharp',
+        projectType: 'api',
+        detect: ctx => buildDetection('aspnet', [
+            evidenceIf(textMatches(ctx.csprojText, /Microsoft\.NET\.Sdk\.Web/i), '.csproj -> Microsoft.NET.Sdk.Web', 4),
+            evidenceIf(textMatches(ctx.programCsText, /WebApplication\.CreateBuilder/i), 'Program.cs -> WebApplication.CreateBuilder', 2)
+        ])
+    },
+    {
+        id: 'tauri',
+        kind: 'desktop',
+        language: 'rust',
+        projectType: 'desktop',
+        detect: ctx => buildDetection('tauri', [
+            evidenceIf(hasDependency(ctx.depNames, '@tauri-apps/api'), 'package.json -> @tauri-apps/api', 4),
+            evidenceIf(ctx.fileExists('src-tauri', 'tauri.conf.json') || ctx.fileExists('src-tauri', 'tauri.conf.json5'), 'found src-tauri/tauri.conf.*', 4),
+            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 2)
+        ])
+    },
+    {
+        id: 'axum',
+        kind: 'backend',
+        language: 'rust',
+        projectType: 'api',
+        detect: ctx => buildDetection('axum', [
+            evidenceIf(textMatches(ctx.cargoText, /\baxum\b/i), 'Cargo.toml -> axum', 4)
+        ])
+    },
+    {
+        id: 'actix',
+        kind: 'backend',
+        language: 'rust',
+        projectType: 'api',
+        detect: ctx => buildDetection('actix', [
+            evidenceIf(textMatches(ctx.cargoText, /\bactix-web\b/i), 'Cargo.toml -> actix-web', 4)
+        ])
+    },
+    {
+        id: 'flutter',
+        kind: 'mobile',
+        projectType: 'mobile',
+        detect: ctx => buildDetection('flutter', [
+            evidenceIf(textMatches(ctx.pubspecText, /^\s*flutter\s*:/im), 'pubspec.yaml -> flutter', 4)
+        ])
+    },
+    {
+        id: 'react-native',
+        kind: 'mobile',
+        projectType: 'mobile',
+        detect: ctx => buildDetection('react-native', [
+            evidenceIf(hasDependency(ctx.depNames, 'react-native', 'expo'), 'package.json -> react-native/expo', 4)
+        ])
+    }
+];
+
+function scanProject() {
+    const appRoot = detectAppRoot(targetDir);
+    const pkg = readJsonIfExistsAt(appRoot, 'package.json') || {};
+    const composer = readJsonIfExistsAt(appRoot, 'composer.json') || {};
+    const rootEntries = fs.existsSync(appRoot) ? fs.readdirSync(appRoot) : [];
+    const rootCsproj = rootEntries.find(name => name.endsWith('.csproj')) || '';
+    const deps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+        ...(pkg.peerDependencies || {})
+    };
+    const depNames = new Set(Object.keys(deps));
+    const composerDeps = {
+        ...(composer.require || {}),
+        ...(composer['require-dev'] || {})
+    };
+    const composerDepNames = new Set(Object.keys(composerDeps));
+    const ctx = {
+        pkg,
+        composer,
+        depNames,
+        composerDepNames,
+        rootEntries,
+        fileExists: (...parts) => fileExistsAt(appRoot, ...parts),
+        requirementsText: readTextIfExistsAt(appRoot, 'requirements.txt'),
+        pyprojectText: readTextIfExistsAt(appRoot, 'pyproject.toml'),
+        goModText: readTextIfExistsAt(appRoot, 'go.mod'),
+        pubspecText: readTextIfExistsAt(appRoot, 'pubspec.yaml'),
+        gemfileText: readTextIfExistsAt(appRoot, 'Gemfile'),
+        pomText: readTextIfExistsAt(appRoot, 'pom.xml'),
+        gradleText: `${readTextIfExistsAt(appRoot, 'build.gradle')}\n${readTextIfExistsAt(appRoot, 'build.gradle.kts')}`,
+        cargoText: `${readTextIfExistsAt(appRoot, 'Cargo.toml')}\n${readTextIfExistsAt(appRoot, 'src-tauri', 'Cargo.toml')}`,
+        csprojText: rootCsproj ? readTextIfExistsAt(appRoot, rootCsproj) : '',
+        programCsText: readTextIfExistsAt(appRoot, 'Program.cs'),
+        viewFilesText: fs.existsSync(path.join(appRoot, 'app', 'View'))
+            ? fs.readdirSync(path.join(appRoot, 'app', 'View'), { recursive: true }).join('\n')
+            : ''
+    };
+
+    const languageDetections = LANGUAGE_DETECTORS
+        .map(detector => detector.detect(ctx))
+        .filter(result => result.score >= 2)
+        .sort((a, b) => b.score - a.score);
+
+    const frameworkDetails = FRAMEWORK_DETECTORS
+        .map(detector => {
+            const result = detector.detect(ctx);
+            if (result.score < 3) return null;
+            return {
+                ...result,
+                kind: detector.kind,
+                language: detector.language,
+                projectType: detector.projectType,
+                confidence: confidenceLabel(result.score)
+            };
+        })
+        .filter(Boolean)
+        .sort((a, b) => b.score - a.score);
+
+    const frameworkLanguageScores = frameworkDetails.reduce((acc, item) => {
+        if (!item.language) return acc;
+        acc[item.language] = (acc[item.language] || 0) + item.score;
+        return acc;
+    }, {});
+    const primaryLanguage = Object.keys(frameworkLanguageScores).sort((a, b) => frameworkLanguageScores[b] - frameworkLanguageScores[a])[0]
+        || languageDetections[0]?.id
+        || 'typescript';
+    const frameworks = uniq(frameworkDetails.map(item => item.id)).filter(name => FRAMEWORK_CHOICES.includes(name));
+    const infrastructure = [];
+    let projectType = '';
+    let database = 'none';
+    let testFramework = 'auto-detect';
+    let cloud = 'none';
+    let ciCd = 'none';
+
+    if (frameworkDetails.some(item => item.projectType === 'desktop')) projectType = 'desktop';
+    else if (frameworkDetails.some(item => item.projectType === 'mobile')) projectType = 'mobile';
+    else if (frameworkDetails.some(item => item.kind === 'frontend') && frameworkDetails.some(item => item.kind === 'backend')) projectType = 'fullstack';
+    else if (frameworkDetails.some(item => item.projectType === 'web-app')) projectType = 'web-app';
+    else if (frameworkDetails.some(item => item.kind === 'backend')) projectType = 'api';
+    else if (frameworkDetails.some(item => item.kind === 'frontend')) projectType = 'web-app';
+    else if (fileExistsAt(appRoot, 'package.json') && pkg.bin) projectType = 'cli';
+    else if (['php', 'python', 'go', 'java', 'ruby', 'csharp', 'rust'].includes(primaryLanguage)) projectType = 'api';
+
+    if (hasDependency(depNames, 'pg', 'postgres', '@prisma/client') || /postgres/i.test(JSON.stringify(pkg))) database = 'postgres';
+    else if (hasDependency(depNames, 'mysql', 'mysql2')) database = 'mysql';
+    else if (hasDependency(depNames, 'sqlite3', 'better-sqlite3', 'rusqlite')) database = 'sqlite';
+    else if (hasDependency(depNames, 'mongodb', 'mongoose')) database = 'mongodb';
+    else if (hasDependency(depNames, 'redis', 'ioredis')) database = 'redis';
+    else if (hasDependency(depNames, '@aws-sdk/client-dynamodb')) database = 'dynamodb';
+
+    if (hasDependency(depNames, 'vitest')) testFramework = 'vitest';
+    else if (hasDependency(depNames, 'jest')) testFramework = 'jest';
+    else if (hasDependency(depNames, 'pytest') || textMatches(ctx.requirementsText, /\bpytest\b/i) || textMatches(ctx.pyprojectText, /\bpytest\b/i)) testFramework = 'pytest';
+    else if (hasComposerDependency(composerDepNames, 'phpunit/phpunit')) testFramework = 'phpunit';
+    else if (hasComposerDependency(composerDepNames, 'pestphp/pest')) testFramework = 'pest';
+    else if (fileExistsAt(appRoot, 'go.mod')) testFramework = 'go test';
+    else if (textMatches(ctx.gemfileText, /^\s*gem\s+["']rspec["']/im)) testFramework = 'rspec';
+
+    if (repoHasAny(targetDir, [['Dockerfile'], ['docker-compose.yml'], ['docker-compose.yaml']])) {
+        infrastructure.push('docker');
+    }
+
+    if (repoHasAny(targetDir, [['vercel.json']])) {
+        cloud = 'vercel';
+        infrastructure.push('vercel');
+    } else if (repoHasAny(targetDir, [['fly.toml']])) {
+        cloud = 'fly';
+        infrastructure.push('fly');
+    } else if (repoHasAny(targetDir, [['railway.json'], ['railway.toml']])) {
+        cloud = 'railway';
+        infrastructure.push('railway');
+    }
+
+    if (repoHasAny(targetDir, [['.github', 'workflows'], ['.gitlab-ci.yml'], ['.circleci', 'config.yml'], ['Jenkinsfile']], 2)) {
+        if (repoHasAny(targetDir, [['.github', 'workflows']], 2)) ciCd = 'github-actions';
+        else if (repoHasAny(targetDir, [['.gitlab-ci.yml']], 2)) ciCd = 'gitlab-ci';
+        else if (repoHasAny(targetDir, [['.circleci', 'config.yml']], 2)) ciCd = 'circleci';
+        else if (repoHasAny(targetDir, [['Jenkinsfile']], 2)) ciCd = 'jenkins';
+    }
+
+    const scanEvidence = [
+        ...(languageDetections[0] ? [`language:${languageDetections[0].id} => ${languageDetections[0].evidence.join('; ')}`] : []),
+        ...frameworkDetails.map(item => `${item.id} [${item.confidence}] => ${item.evidence.join('; ')}`)
+    ];
+
+    return {
+        project_name: path.basename(targetDir),
+        app_root: path.relative(targetDir, appRoot) || '.',
+        description: pkg.description || composer.description || 'A software project',
+        project_type: PROJECT_TYPE_CHOICES.includes(projectType) ? projectType : 'web-app',
+        primary_language: LANGUAGE_CHOICES.includes(primaryLanguage) ? primaryLanguage : 'typescript',
+        frameworks,
+        framework_details: frameworkDetails,
+        scan_evidence: scanEvidence,
+        database: DATABASE_CHOICES.includes(database) ? database : 'none',
+        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager(appRoot)) ? detectPackageManager(appRoot) : 'auto-detect',
+        uses_docker: infrastructure.includes('docker'),
+        cloud,
+        infrastructure: uniq(infrastructure),
+        ci_cd: ciCd,
+        test_framework: TEST_FRAMEWORK_CHOICES.includes(testFramework) ? testFramework : 'auto-detect',
+        max_file_lines: '300',
+        code_style: 'project-standard',
+        architecture_notes: '<!-- Add notes -->',
+        current_phase: 'Initial setup',
+        next_phase: '—',
+        known_issues: '<!-- None yet -->'
+    };
+}
 
 function resolveAgentTable(data) {
     const rows = [];
@@ -804,7 +811,7 @@ function resolveAgentTable(data) {
     const lang = (data.primary_language || "").toLowerCase();
 
     // Frontend
-    const frontendFws = frameworks.filter(f => FRONTEND_FRAMEWORKS.includes(f));
+    const frontendFws = frameworks.filter(f => FRONTEND_FRAMEWORKS.includes(f));
     if (frontendFws.length > 0) {
         let feSkills = [];
         frontendFws.forEach(fw => {
@@ -815,14 +822,14 @@ function resolveAgentTable(data) {
 
     // Backend
     let beSkills = [...(LANG_SKILLS[lang] || ["api-design"])];
-    const backendFws = frameworks.filter(f => BACKEND_FRAMEWORKS.includes(f));
+    const backendFws = frameworks.filter(f => BACKEND_FRAMEWORKS.includes(f));
     backendFws.forEach(fw => {
         beSkills.push(...(FRAMEWORK_SKILLS[fw] || []));
     });
     rows.push(["Backend API", "backend-specialist", Array.from(new Set(beSkills)).slice(0, 3).join(", ")]);
 
     // Mobile/Desktop
-    const mobileFws = frameworks.filter(f => MOBILE_DESKTOP_FRAMEWORKS.includes(f));
+    const mobileFws = frameworks.filter(f => MOBILE_DESKTOP_FRAMEWORKS.includes(f));
     if (mobileFws.length > 0) {
         let mobileSkills = [];
         mobileFws.forEach(fw => {
@@ -845,617 +852,523 @@ function resolveAgentTable(data) {
 
 // --- File Generators ---
 
-function generateProjectContext(data) {
-    const agentTable = resolveAgentTable(data);
-    const autoSkills = resolveSkills(data);
-    const scanEvidenceBlock = (data.scan_evidence || []).length > 0
-        ? `
----
-
-## Scan Evidence
-
-These detections were inferred from the current codebase during \`init --scan\`:
-
-\`\`\`text
-${(data.scan_evidence || []).map(line => '- ' + line).join('\n')}
-\`\`\`
-`
-        : '';
-
-    const agentRows = agentTable.map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
-    const autoSkillsList = autoSkills.map(s => `- ${s}`).join('\n');
-
-    return `# PROJECT_CONTEXT.md
-# Generated by thachvd-kit init wizard on ${new Date().toISOString().split('T')[0]}
-# Edit freely — this is your project's brain.
-
-## Project
-
-- **Name:** ${data.project_name}
-- **Description:** ${data.description}
-- **Type:** ${data.project_type}
-
----
-
-## Context Status
-
-\`\`\`yaml
-context:
-  status: ${data.context_status || 'baseline'}
-  needs_ai_refinement: ${data.needs_ai_refinement ? 'true' : 'false'}
-  last_refined_at: ${data.last_refined_at || 'not-yet-refined'}
-\`\`\`
-
----
-
-## Stack
+function generateSharedAgentsMd(data) {
+    return `# AGENTS.md
 
-\`\`\`yaml
-stack:
-  app_root: ${data.app_root || '.'}
-  primary_language: ${data.primary_language}
-  frameworks: [${(data.frameworks || []).join(', ')}]
-  database: ${data.database || 'none'}
-  infrastructure: [${(data.infrastructure || []).join(', ')}]
-  package_manager: ${data.package_manager || 'auto-detect'}
-  test_framework: ${data.test_framework || 'auto-detect'}
-\`\`\`
-
-${scanEvidenceBlock}
-
----
-
-## Agent Routing
+Shared operating instructions for Codex, Antigravity, and Claude Code.
 
-| Task Type | Agent | Primary Skills |
-|-----------|-------|----------------|
-${agentRows}
+## Startup
 
----
+1. Read this file first.
+2. Read \`.agent/docs/project.md\` for detected stack, commands, and routing.
+3. Read \`.agent/docs/workflow.md\` for the task flow before editing.
+4. Read \`.agent/docs/architecture.md\` and \`.agent/docs/conventions.md\` before planning code changes.
+5. Load only the agent, skill, or workflow files that match the current task.
 
-## Auto-Resolved Skills
+If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
 
-Based on your stack, these skills will be loaded automatically:
+## Task Flow
 
-\`\`\`text
-${autoSkillsList}
-\`\`\`
+- Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
+- Simple fix: inspect dependencies, make the smallest change, run focused verification.
+- Feature or refactor: define success criteria, make a short plan, implement, then verify.
+- Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
+- UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
 
----
+## Rules
 
-## Project Conventions
+- Respond in the user's language; keep code, identifiers, and code comments in English.
+- State assumptions when the request is ambiguous.
+- Prefer the existing project style over new abstractions.
+- Keep changes surgical and remove only dead code introduced by your change.
+- Tests or equivalent verification are mandatory before claiming done.
+- Keep files under ${data.max_file_lines || '300'} lines unless the project already has a different standard in \`.agent/docs/conventions.md\`.
 
-- **Max file size:** ${data.max_file_lines || '300'} lines (then modularize)
-- **Code style:** ${data.code_style || 'project-standard'}
+## Shared Knowledge
 
----
-
-## Architecture Notes
-
-<!-- Add architecture notes, key decisions, patterns used -->
+- Project docs: \`.agent/docs/\`
+- Specialist agents: \`.agent/agents/\`
+- Skills: \`.agent/skills/\`
+- Workflows: \`.agent/workflows/\`
+- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
+`;
+}
 
----
+function generateSharedClaudeMd() {
+    return `@AGENTS.md
 
-## Current Phase
+## Claude Code
 
-- **Done:** —
-- **In Progress:** Initial setup
-- **Next:** —
+This repository uses AGENTS.md as the shared cross-agent entry file. Follow the imported instructions and keep Claude-specific notes here only when they cannot apply to Codex or Antigravity.
+`;
+}
 
+function generateSharedGeminiMd() {
+    return `# GEMINI.md
 
----
-
-## Known Issues / Tasks
-
-<!-- Add known issues or pending tasks -->
-`;
-}
-
-
-function generateClaudeMd(data) {
-    return `# CLAUDE.md — ${data.project_name}
-# Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
-# Platform: Claude Code
-
-## Project
-${data.description}
-Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ')}
-
-## Rules
-- Read PROJECT_CONTEXT.md first for stack details and agent routing.
-- If PROJECT_CONTEXT.md is missing or stale, create/update it before major work.
-- Follow skills in .agent/skills/ (or .claude/skills/).
-- Tests are mandatory. Verify before claiming done.
-- Max ${data.max_file_lines || '300'} lines per file.
+Antigravity entry file for this project.
 
-## Key Skills
-- Plan: \`plan-writing\` → \`executing-plans\`
-- Review: \`requesting-code-review\` / \`receiving-code-review\`
-- Quality: \`clean-code\`, \`verification-before-completion\`
-- Workflow: \`subagent-driven-development\`, \`finishing-a-development-branch\`
-
-## Commands
-- \`/plan\` — Create implementation plan
-- \`/debug\` — Systematic debugging
-- \`/test\` — Run test suite
-- \`/deploy\` — Deploy checklist
-
-See PROJECT_CONTEXT.md for full agent routing table.
+Read AGENTS.md first, then follow the shared docs under .agent/docs/.
 `;
 }
 
-function generateAgentsMd(data) {
-    const frameworks = (data.frameworks || []);
+function resolveCommands(data) {
+    const frameworks = data.frameworks || [];
     const primaryLang = data.primary_language || 'javascript';
     const pkgManager = data.package_manager || 'npm';
     const testFramework = data.test_framework || 'auto-detect';
-    const database = data.database || 'none';
-    const cloud = data.cloud || 'none';
-    const infrastructure = (data.infrastructure || []);
-    const appRoot = data.app_root || '.';
-    const maxFileLines = data.max_file_lines || '300';
 
-    // Build dev commands section based on detected package manager and framework
-    const isNode = ['javascript', 'typescript'].includes(primaryLang);
     const isPython = primaryLang === 'python';
     const isGo = primaryLang === 'go';
     const isRust = primaryLang === 'rust';
     const isPhp = primaryLang === 'php';
 
-    let installCmd = 'npm install';
-    let devCmd = 'npm run dev';
-    let buildCmd = 'npm run build';
-    let testCmd = 'npm test';
-    let lintCmd = 'npm run lint';
-
-    if (pkgManager === 'pnpm') { installCmd = 'pnpm install'; devCmd = 'pnpm dev'; buildCmd = 'pnpm build'; testCmd = 'pnpm test'; lintCmd = 'pnpm lint'; }
-    else if (pkgManager === 'yarn') { installCmd = 'yarn'; devCmd = 'yarn dev'; buildCmd = 'yarn build'; testCmd = 'yarn test'; lintCmd = 'yarn lint'; }
-    else if (pkgManager === 'bun') { installCmd = 'bun install'; devCmd = 'bun dev'; buildCmd = 'bun run build'; testCmd = 'bun test'; lintCmd = 'bun run lint'; }
-    else if (isPython) { installCmd = 'pip install -r requirements.txt'; devCmd = 'python manage.py runserver'; buildCmd = '# no build step'; testCmd = 'pytest'; lintCmd = 'ruff check .'; }
-    else if (isGo) { installCmd = 'go mod download'; devCmd = 'go run .'; buildCmd = 'go build ./...'; testCmd = 'go test ./...'; lintCmd = 'golangci-lint run'; }
-    else if (isRust) { installCmd = 'cargo build'; devCmd = 'cargo run'; buildCmd = 'cargo build --release'; testCmd = 'cargo test'; lintCmd = 'cargo clippy'; }
+    let install = 'npm install';
+    let dev = 'npm run dev';
+    let build = 'npm run build';
+    let test = 'npm test';
+    let lint = 'npm run lint';
+
+    if (pkgManager === 'pnpm') { install = 'pnpm install'; dev = 'pnpm dev'; build = 'pnpm build'; test = 'pnpm test'; lint = 'pnpm lint'; }
+    else if (pkgManager === 'yarn') { install = 'yarn'; dev = 'yarn dev'; build = 'yarn build'; test = 'yarn test'; lint = 'yarn lint'; }
+    else if (pkgManager === 'bun') { install = 'bun install'; dev = 'bun dev'; build = 'bun run build'; test = 'bun test'; lint = 'bun run lint'; }
+    else if (isPython) { install = 'pip install -r requirements.txt'; dev = 'python manage.py runserver'; build = '# no build step'; test = 'pytest'; lint = 'ruff check .'; }
+    else if (isGo) { install = 'go mod download'; dev = 'go run .'; build = 'go build ./...'; test = 'go test ./...'; lint = 'golangci-lint run'; }
+    else if (isRust) { install = 'cargo build'; dev = 'cargo run'; build = 'cargo build --release'; test = 'cargo test'; lint = 'cargo clippy'; }
     else if (isPhp) {
-        installCmd = 'composer install';
-        buildCmd = '# no build step';
-        testCmd = testFramework === 'pest' ? './vendor/bin/pest' : './vendor/bin/phpunit';
+        install = 'composer install';
+        build = '# no build step';
+        test = testFramework === 'pest' ? './vendor/bin/pest' : './vendor/bin/phpunit';
         const isCakePHP = frameworks.some(f => f.toLowerCase().includes('cakephp'));
         const isSymfony = frameworks.some(f => f.toLowerCase().includes('symfony'));
         const isCodeIgniter = frameworks.some(f => f.toLowerCase().includes('codeigniter'));
         if (isCakePHP) {
-            devCmd = 'bin/cake server';
-            lintCmd = './vendor/bin/phpcs';
+            dev = 'bin/cake server';
+            lint = './vendor/bin/phpcs';
         } else if (isSymfony) {
-            devCmd = 'bin/console server:run';
-            lintCmd = './vendor/bin/phpcs';
+            dev = 'bin/console server:run';
+            lint = './vendor/bin/phpcs';
         } else if (isCodeIgniter) {
-            devCmd = 'php spark serve';
-            lintCmd = './vendor/bin/phpcs';
+            dev = 'php spark serve';
+            lint = './vendor/bin/phpcs';
         } else {
-            // Default: Laravel
-            devCmd = 'php artisan serve';
-            lintCmd = 'php artisan pint';
+            dev = 'php artisan serve';
+            lint = 'php artisan pint';
         }
     }
 
-    if (testFramework === 'vitest') testCmd = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : pkgManager === 'bun' ? 'bun run' : 'npx'} vitest`;
-    else if (testFramework === 'jest') testCmd = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : 'npx'} jest`;
-
-    // Build stack overview section
-    const stackLines = [
-        `- **Language:** ${primaryLang}`,
-        frameworks.length > 0 ? `- **Frameworks:** ${frameworks.join(', ')}` : null,
-        database !== 'none' ? `- **Database:** ${database}` : null,
-        pkgManager !== 'auto-detect' ? `- **Package Manager:** ${pkgManager}` : null,
-        testFramework !== 'auto-detect' ? `- **Test Framework:** ${testFramework}` : null,
-        cloud !== 'none' ? `- **Cloud:** ${cloud}` : null,
-        infrastructure.length > 0 ? `- **Infrastructure:** ${infrastructure.join(', ')}` : null,
-    ].filter(Boolean).join('\n');
-
-    // Build architecture notes hint
-    const archNotes = data.architecture_notes && !data.architecture_notes.includes('<!-- Add')
-        ? `\n${data.architecture_notes}`
-        : '';
-
-    // Agent routing table
-    const agentTable = resolveAgentTable(data);
-    const agentRows = agentTable.map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
-
-    // Auto-resolved skills
-    const autoSkills = resolveSkills(data);
-    const skillsList = autoSkills.map(s => `- ${s}`).join('\n');
-
-    return `# ${data.project_name}
-
-${data.description}
-
-## Project Overview
-
-${stackLines}
-
----
-
-## Core Architecture
-
-<!-- AI: Scan the project and replace this section with actual directory structure and key module descriptions -->
-${appRoot !== '.' ? `- **App Root:** \`${appRoot}\`` : ''}
-
----
-
-## Development Workflow
-
-### Prerequisites
-- ${primaryLang.charAt(0).toUpperCase() + primaryLang.slice(1)} toolchain installed
-${pkgManager !== 'auto-detect' ? `- \`${pkgManager}\` (Package Manager)` : ''}
-
-### Key Commands
-- **Install Dependencies:** \`${installCmd}\`
-- **Development Server:** \`${devCmd}\`
-- **Build for Production:** \`${buildCmd}\`
-- **Run Tests:** \`${testCmd}\`
-- **Linting:** \`${lintCmd}\`
-
----
-
-## Coding Conventions
-
-<!-- AI: Scan the project and replace this section with actual conventions (API patterns, state management, styling, naming, routing) -->
-
----
-
-## Performance & Optimization
-
-<!-- AI: Scan vite.config / webpack / build config and replace with actual optimizations used -->
-
----
-
-## Coding Rules
+    if (testFramework === 'vitest') test = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : pkgManager === 'bun' ? 'bun run' : 'npx'} vitest`;
+    else if (testFramework === 'jest') test = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : 'npx'} jest`;
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-### 1. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-### 2. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-### 3. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-\`\`\`
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-\`\`\`
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-### 4. Universal Standards
-
-- Respond in user's language; code/comments in English.
-- \`clean-code\` applies to all code, all languages.
-- Tests are mandatory.
-- Verify with evidence before claiming done.
-- Identify dependent files before modifying any.
-- Keep files under ${maxFileLines} lines; split into modules if exceeded.
-`;
+    return { install, dev, build, test, lint };
 }
 
-function generateAgentsMdRefinementPrompt(data) {
-    const evidence = (data.scan_evidence || []).length > 0
-        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
-        : '- No scan evidence was captured during init.';
-
-    return `# AGENTS.md Refinement Prompt
-
-Run this in your AI editor right after \`thachvd-kit init --scan\`.
-The goal is to replace the placeholder sections in \`AGENTS.md\` with real project knowledge.
-
-## Baseline Detected
-
-- **Project:** ${data.project_name}
-- **Stack:** ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
-- **Database:** ${data.database || 'none'}
-- **Package Manager:** ${data.package_manager || 'auto-detect'}
-
-## Scan Evidence
-
-${evidence}
-
-## Your Task
-
-Update **only** the placeholder sections in \`AGENTS.md\` (marked with \`<!-- AI: ... --\`>):
-
-### 1. Core Architecture
-Scan the \`src/\` (or equivalent) directory. For each major folder, write one bullet:
-\`- **\`src/folder/\`**: What it contains and its role\`
-Keep it concise — one line per folder.
-
-### 2. Coding Conventions
-Inspect actual code patterns and write conventions grouped by topic:
-- API integration patterns (how HTTP calls are made)
-- State management patterns
-- Styling conventions
-- Component/file naming rules
-- Routing and auth patterns
-
-### 3. Performance & Optimization
-Check \`vite.config.js\`, \`webpack.config.js\`, \`package.json\` scripts, or build configs. List actual optimizations:
-- Code splitting, lazy loading, chunking
-- Compression, caching strategies
-- PWA, image optimization, etc.
-
-## Rules
-
-- Replace placeholders with real content. Remove the \`<!-- AI: ... -->\` comments.
-- Do NOT change \`## Project Overview\`, \`## Development Workflow\`, or \`## Coding Rules\` sections.
-- Do NOT implement any product code.
-- If a section is not applicable, write \`N/A\` and remove the placeholder.
-
-## Files To Inspect
-
-- \`src/\` or \`app/\` directory structure
-- Build config: \`vite.config.*\`, \`webpack.config.*\`, \`next.config.*\`
-- Entry points: \`main.js\`, \`app.js\`, \`index.ts\`
-- Router definition
-- Example API service files
-- Example store/state files
-- README if present
-`;
-}
+function generateProjectDoc(data) {
+    const commands = resolveCommands(data);
+    const agentRows = resolveAgentTable(data).map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
+    const skillsList = resolveSkills(data).map(s => `- ${s}`).join('\n');
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine scan evidence by inspecting the project.';
 
-// --- Main CLI ---
+    return `# Project Rules
 
-async function main() {
-    const rawArgs = process.argv.slice(2);
-    const command = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : 'init';
-    const args = command === 'init' ? rawArgs.slice(rawArgs[0] === 'init' ? 1 : 0) : rawArgs.slice(1);
-
-    if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
-        console.log(packageJson.version);
-        return;
-    }
-
-    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
-        printHelp();
-        return;
-    }
-
-    if (command !== 'init') {
-        console.error(pc.red(`Unknown command: ${command}`));
-        printHelp();
-        process.exit(1);
-    }
-
-    let useScan = args.includes('--scan');
-    const assumeYes = args.includes('--yes') || args.includes('-y');
-
-    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
-    console.log('  ' + pc.bold('thachvd-kit') + ' — Project Init Wizard');
-    console.log(`  Generates AGENTS.md${useScan ? ' (scan-assisted)' : ''}`);
-    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')) + '\n');
-
-    let projectSetup = 'new';
-    if (!useScan && !assumeYes) {
-        const modeAnswer = await askQuestions([
-            {
-                type: 'select',
-                name: 'project_setup',
-                message: 'Project already exists or are you starting fresh?',
-                choices: [
-                    { title: 'Existing project', value: 'existing' },
-                    { title: 'New project', value: 'new' }
-                ]
-            },
-            {
-                type: prev => prev === 'existing' ? 'select' : null,
-                name: 'existing_mode',
-                message: 'How should thachvd-kit build PROJECT_CONTEXT.md?',
-                choices: [
-                    { title: 'Scan current project files', value: 'scan' },
-                    { title: 'Enter context manually', value: 'manual' }
-                ],
-                initial: 0
+Generated by thachvd-kit on ${new Date().toISOString().split('T')[0]}.
+
+## Summary
+
+- Name: ${data.project_name}
+- Description: ${data.description}
+- Type: ${data.project_type}
+- App root: ${data.app_root || '.'}
+
+## Stack
+
+- Language: ${data.primary_language}
+- Frameworks: ${(data.frameworks || []).join(', ') || 'none'}
+- Database: ${data.database || 'none'}
+- Infrastructure: ${(data.infrastructure || []).join(', ') || 'none'}
+- Package manager: ${data.package_manager || 'auto-detect'}
+- Test framework: ${data.test_framework || 'auto-detect'}
+
+## Commands
+
+- Install: \`${commands.install}\`
+- Dev: \`${commands.dev}\`
+- Build: \`${commands.build}\`
+- Test: \`${commands.test}\`
+- Lint: \`${commands.lint}\`
+
+## Agent Routing
+
+| Task Type | Agent | Primary Skills |
+|-----------|-------|----------------|
+${agentRows}
+
+## Auto-Resolved Skills
+
+${skillsList}
+
+## Scan Evidence
+
+${evidence}
+`;
+}
+
+function generateArchitectureDoc(data) {
+    const appRootLine = data.app_root && data.app_root !== '.'
+        ? `- App root is currently detected as \`${data.app_root}\`.`
+        : '- App root is the repository root unless refined below.';
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine architecture by scanning source directories.';
+
+    return `# Architecture Notes
+
+## Current Map
+
+${appRootLine}
+- TODO: refine major directories and responsibilities.
+- TODO: refine main entry points, routing, state boundaries, and integration boundaries.
+
+## Detected Evidence
+
+${evidence}
+
+## AI Maintenance Rule
+
+Before non-trivial implementation work, inspect this file. If it is stale or still contains TODO items relevant to the task, update it from the code before editing product code.
+`;
+}
+
+function generateConventionsDoc(data) {
+    return `# Coding Conventions
+
+## Current Standards
+
+- Maximum file length: ${data.max_file_lines || '300'} lines unless the existing project standard is stricter.
+- Code comments and identifiers should be written in English.
+- Keep changes scoped to the user request.
+- Prefer existing local patterns over introducing new abstractions.
+- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
+
+## Verification
+
+- Run the focused test or lint command that matches the touched area.
+- If no automated check exists, document the manual verification performed.
+- Do not claim completion without verification evidence.
+`;
+}
+
+function generateWorkflowDoc() {
+    return `# Agent Workflow
+
+## Before Every Task
+
+1. Read AGENTS.md.
+2. Read .agent/docs/project.md.
+3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
+4. Read only the relevant docs under .agent/agents, .agent/skills, and .agent/workflows.
+
+## Implementation Flow
+
+1. State assumptions and success criteria when the task is not trivial.
+2. Inspect dependent files before editing.
+3. Make the smallest coherent change.
+4. Add or update focused tests when behavior changes.
+5. Run verification.
+6. Summarize changed files and verification evidence.
+
+## When To Update Docs
+
+- Update .agent/docs/architecture.md when structure, boundaries, or entry points change.
+- Update .agent/docs/conventions.md when repeated project patterns become clear.
+- Update .agent/docs/project.md when stack, scripts, app root, test tooling, or routing changes.
+- Keep AGENTS.md concise. Put project-specific detail in .agent/docs.
+`;
+}
+
+// --- Agent Folder Copy ---
+
+function copyAgentFolder() {
+    const srcAgent = path.join(sourceDir, '.agent');
+    if (!fs.existsSync(srcAgent)) return { copied: 0, skipped: 0 };
+
+    const destAgent = path.join(targetDir, '.agent');
+    let copied = 0;
+    let skipped = 0;
+
+    function copyDir(src, dest) {
+        fs.mkdirSync(dest, { recursive: true });
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            const relativeSrc = path.relative(srcAgent, srcPath).split(path.sep).join('/');
+            if (relativeSrc === 'docs' || relativeSrc.startsWith('docs/')) {
+                continue;
             }
-        ]);
-        projectSetup = modeAnswer.project_setup || 'new';
-        useScan = modeAnswer.existing_mode === 'scan';
-    }
-
-    if (useScan) {
-        console.log(pc.dim('  Scan mode: detecting stack from current project files...\n'));
-    } else if (projectSetup === 'new') {
-        console.log(pc.dim('  Manual mode: asking for project context explicitly.\n'));
-    }
-
-    if (fs.existsSync(path.join(targetDir, 'PROJECT_CONTEXT.md')) && !assumeYes) {
-        const res = await askQuestions({
-            type: 'confirm',
-            name: 'overwrite',
-            message: 'PROJECT_CONTEXT.md already exists in this folder. Overwrite?',
+            if (entry.isDirectory()) {
+                copyDir(srcPath, destPath);
+            } else {
+                if (fs.existsSync(destPath)) {
+                    skipped++;
+                } else {
+                    fs.copyFileSync(srcPath, destPath);
+                    copied++;
+                }
+            }
+        }
+    }
+
+    copyDir(srcAgent, destAgent);
+    return { copied, skipped };
+}
+
+async function writeGeneratedFile(relativePath, content, assumeYes) {
+    const outputPath = path.join(targetDir, relativePath);
+    const exists = fs.existsSync(outputPath);
+    if (exists && !assumeYes) {
+        const res = await askQuestions({
+            type: 'confirm',
+            name: 'overwrite',
+            message: `${relativePath} already exists. Overwrite?`,
             initial: false
         });
-        if (!res.overwrite) {
-            console.log(pc.yellow('\nAborted. Existing project context unchanged.'));
-            process.exit(0);
-        }
-    }
-
-    const scanned = useScan ? scanProject() : null;
-    let reviewScannedFields = !useScan;
-    let requestAiRefinement = false;
-
-    if (useScan) {
-        console.log(`  ${pc.bold('Detected context:')}`);
-        formatScanPreviewLines(scanned).forEach(([label, value]) => {
-            console.log(`    · ${label}: ${value}`);
-        });
-        console.log('');
-        if ((scanned.scan_evidence || []).length > 0) {
-            console.log(`  ${pc.bold('Evidence:')}`);
-            scanned.scan_evidence.forEach(line => console.log(`    · ${line}`));
-            console.log('');
-        }
-
-        if (!assumeYes) {
-            const scanAction = await askQuestions({
-                type: 'select',
-                name: 'scan_action',
-                message: 'Use detected context as-is or review fields manually?',
-                choices: [
-                    { title: 'Use detected context', value: 'accept' },
-                    { title: 'Review detected fields', value: 'review' }
-                ],
-                initial: 0
-            });
-            reviewScannedFields = scanAction.scan_action === 'review';
-        }
-    }
-
-    const { project_name, description, project_type } = await askQuestions([
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'project_name', message: 'Project name:', initial: scanned?.project_name || path.basename(targetDir) },
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'description', message: 'Short description:', initial: scanned?.description || 'A software project' },
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'project_type', message: 'Project type:',
-            choices: PROJECT_TYPE_CHOICES.map(value => ({ title: value, value })),
-            initial: Math.max(PROJECT_TYPE_CHOICES.indexOf(scanned?.project_type || 'web-app'), 0)
-        }
-    ]);
-
-    const { primary_language } = await askQuestions({
-        type: assumeYes || !reviewScannedFields ? null : 'select',
-        name: 'primary_language',
-        message: 'Primary language:',
-        choices: LANGUAGE_CHOICES.map(l => ({ title: l, value: l })),
-        initial: Math.max(LANGUAGE_CHOICES.indexOf(scanned?.primary_language || 'typescript'), 0)
-    });
-
-    const { frameworks } = await askQuestions({
-        type: assumeYes || !reviewScannedFields ? null : 'multiselect',
-        name: 'frameworks',
-        message: 'Frameworks (Space to select, Enter to confirm):',
-        choices: FRAMEWORK_CHOICES.map(f => ({ title: f, value: f, selected: (scanned?.frameworks || []).includes(f) })),
-        min: 0
-    });
-
-    const dbAndInfra = await askQuestions([
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'database', message: 'Database / ORM:',
-            choices: DATABASE_CHOICES.map(d => ({ title: d, value: d })),
-            initial: Math.max(DATABASE_CHOICES.indexOf(scanned?.database || 'none'), 0)
-        },
-        { type: assumeYes || !reviewScannedFields ? null : 'confirm', name: 'uses_docker', message: 'Uses Docker / Docker Compose?', initial: scanned?.uses_docker ?? true },
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'cloud', message: 'Cloud Provider:',
-            choices: CLOUD_CHOICES.map(c => ({ title: c, value: c })),
-            initial: Math.max(CLOUD_CHOICES.indexOf(scanned?.cloud || 'none'), 0)
-        }
-    ]);
-
-    const { package_manager, test_framework, max_file_lines } = await askQuestions([
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'package_manager', message: 'Package Manager:',
-            choices: PACKAGE_MANAGER_CHOICES.map(p => ({ title: p, value: p })),
-            initial: Math.max(PACKAGE_MANAGER_CHOICES.indexOf(scanned?.package_manager || 'auto-detect'), 0)
-        },
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'test_framework', message: 'Test Framework (jest, phpunit, etc):', initial: scanned?.test_framework || 'auto-detect' },
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'max_file_lines', message: 'Max lines per file:', initial: scanned?.max_file_lines || '300' }
-    ]);
-
-    // Combine data
-    const data = {
-        project_name: project_name || scanned?.project_name || path.basename(targetDir),
-        description: description || scanned?.description || 'A software project',
-        project_type: project_type || scanned?.project_type || 'web-app',
-        primary_language: primary_language || scanned?.primary_language || 'typescript',
-        frameworks: frameworks || scanned?.frameworks || [],
-        ...dbAndInfra, package_manager, test_framework, max_file_lines
-    };
-
-    data.database = data.database || scanned?.database || 'none';
-    data.uses_docker = typeof data.uses_docker === 'boolean' ? data.uses_docker : (scanned?.uses_docker ?? true);
-    data.cloud = data.cloud || scanned?.cloud || 'none';
-    data.package_manager = data.package_manager || scanned?.package_manager || 'auto-detect';
-    data.test_framework = data.test_framework || scanned?.test_framework || 'auto-detect';
-    data.max_file_lines = data.max_file_lines || scanned?.max_file_lines || '300';
-    data.framework_details = scanned?.framework_details || [];
-    data.scan_evidence = scanned?.scan_evidence || [];
-    data.app_root = scanned?.app_root || '.';
-
-    data.infrastructure = [];
-    if (data.uses_docker) data.infrastructure.push('docker');
-    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
-
-    console.log(`\n${pc.bold(pc.cyan('━━ Generating Files ━━'))}`);
-
-    // Write AGENTS.md — the only output file
-    const agentsMdPath = path.join(targetDir, 'AGENTS.md');
-    const agentsMdExists = fs.existsSync(agentsMdPath);
-    if (agentsMdExists && !assumeYes) {
-        const res = await askQuestions({
-            type: 'confirm',
-            name: 'overwrite',
-            message: 'AGENTS.md already exists. Overwrite?',
-            initial: false
-        });
-        if (!res.overwrite) {
-            console.log(pc.yellow('\nAborted. Existing AGENTS.md unchanged.'));
-            process.exit(0);
-        }
-    }
-
-    fs.writeFileSync(agentsMdPath, generateAgentsMd(data), 'utf8');
-    console.log(`  ${pc.green('✓')} Generated ${pc.bold('AGENTS.md')}`);
-
-    console.log(`\n${pc.bold(pc.green('━━ Done! ━━'))}
-
-  ${pc.bold('Project:')} ${data.project_name}
-  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
-
-  ${pc.bold('Generated:')} ${pc.bold(agentsMdPath)}
-
+        if (!res.overwrite) return false;
+    }
+
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, content, 'utf8');
+    return true;
+}
+
+// --- Main CLI ---
+
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    const command = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : 'init';
+    const args = command === 'init' ? rawArgs.slice(rawArgs[0] === 'init' ? 1 : 0) : rawArgs.slice(1);
+
+    if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
+        console.log(packageJson.version);
+        return;
+    }
+
+    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        printHelp();
+        return;
+    }
+
+    if (command !== 'init') {
+        console.error(pc.red(`Unknown command: ${command}`));
+        printHelp();
+        process.exit(1);
+    }
+
+    let useScan = args.includes('--scan');
+    const assumeYes = args.includes('--yes') || args.includes('-y');
+
+    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+    console.log('  ' + pc.bold('thachvd-kit') + ' — Project Init Wizard');
+    console.log(`  Generates AGENTS.md + .agent/ folder${useScan ? ' (scan-assisted)' : ''}`);
+    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')) + '\n');
+
+    let projectSetup = 'new';
+    if (!useScan && !assumeYes) {
+        const modeAnswer = await askQuestions([
+            {
+                type: 'select',
+                name: 'project_setup',
+                message: 'Project already exists or are you starting fresh?',
+                choices: [
+                    { title: 'Existing project', value: 'existing' },
+                    { title: 'New project', value: 'new' }
+                ]
+            },
+            {
+                type: prev => prev === 'existing' ? 'select' : null,
+                name: 'existing_mode',
+                message: 'How should thachvd-kit build project rules?',
+                choices: [
+                    { title: 'Scan current project files', value: 'scan' },
+                    { title: 'Enter context manually', value: 'manual' }
+                ],
+                initial: 0
+            }
+        ]);
+        projectSetup = modeAnswer.project_setup || 'new';
+        useScan = modeAnswer.existing_mode === 'scan';
+    }
+
+    if (useScan) {
+        console.log(pc.dim('  Scan mode: detecting stack from current project files...\n'));
+    } else if (projectSetup === 'new') {
+        console.log(pc.dim('  Manual mode: asking for project context explicitly.\n'));
+    }
+
+    const scanned = useScan ? scanProject() : null;
+    let reviewScannedFields = !useScan;
+    let requestAiRefinement = false;
+
+    if (useScan) {
+        console.log(`  ${pc.bold('Detected context:')}`);
+        formatScanPreviewLines(scanned).forEach(([label, value]) => {
+            console.log(`    · ${label}: ${value}`);
+        });
+        console.log('');
+        if ((scanned.scan_evidence || []).length > 0) {
+            console.log(`  ${pc.bold('Evidence:')}`);
+            scanned.scan_evidence.forEach(line => console.log(`    · ${line}`));
+            console.log('');
+        }
+
+        if (!assumeYes) {
+            const scanAction = await askQuestions({
+                type: 'select',
+                name: 'scan_action',
+                message: 'Use detected context as-is or review fields manually?',
+                choices: [
+                    { title: 'Use detected context', value: 'accept' },
+                    { title: 'Review detected fields', value: 'review' }
+                ],
+                initial: 0
+            });
+            reviewScannedFields = scanAction.scan_action === 'review';
+        }
+    }
+
+    const { project_name, description, project_type } = await askQuestions([
+        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'project_name', message: 'Project name:', initial: scanned?.project_name || path.basename(targetDir) },
+        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'description', message: 'Short description:', initial: scanned?.description || 'A software project' },
+        {
+            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'project_type', message: 'Project type:',
+            choices: PROJECT_TYPE_CHOICES.map(value => ({ title: value, value })),
+            initial: Math.max(PROJECT_TYPE_CHOICES.indexOf(scanned?.project_type || 'web-app'), 0)
+        }
+    ]);
+
+    const { primary_language } = await askQuestions({
+        type: assumeYes || !reviewScannedFields ? null : 'select',
+        name: 'primary_language',
+        message: 'Primary language:',
+        choices: LANGUAGE_CHOICES.map(l => ({ title: l, value: l })),
+        initial: Math.max(LANGUAGE_CHOICES.indexOf(scanned?.primary_language || 'typescript'), 0)
+    });
+
+    const { frameworks } = await askQuestions({
+        type: assumeYes || !reviewScannedFields ? null : 'multiselect',
+        name: 'frameworks',
+        message: 'Frameworks (Space to select, Enter to confirm):',
+        choices: FRAMEWORK_CHOICES.map(f => ({ title: f, value: f, selected: (scanned?.frameworks || []).includes(f) })),
+        min: 0
+    });
+
+    const dbAndInfra = await askQuestions([
+        {
+            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'database', message: 'Database / ORM:',
+            choices: DATABASE_CHOICES.map(d => ({ title: d, value: d })),
+            initial: Math.max(DATABASE_CHOICES.indexOf(scanned?.database || 'none'), 0)
+        },
+        { type: assumeYes || !reviewScannedFields ? null : 'confirm', name: 'uses_docker', message: 'Uses Docker / Docker Compose?', initial: scanned?.uses_docker ?? true },
+        {
+            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'cloud', message: 'Cloud Provider:',
+            choices: CLOUD_CHOICES.map(c => ({ title: c, value: c })),
+            initial: Math.max(CLOUD_CHOICES.indexOf(scanned?.cloud || 'none'), 0)
+        }
+    ]);
+
+    const { package_manager, test_framework, max_file_lines } = await askQuestions([
+        {
+            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'package_manager', message: 'Package Manager:',
+            choices: PACKAGE_MANAGER_CHOICES.map(p => ({ title: p, value: p })),
+            initial: Math.max(PACKAGE_MANAGER_CHOICES.indexOf(scanned?.package_manager || 'auto-detect'), 0)
+        },
+        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'test_framework', message: 'Test Framework (jest, phpunit, etc):', initial: scanned?.test_framework || 'auto-detect' },
+        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'max_file_lines', message: 'Max lines per file:', initial: scanned?.max_file_lines || '300' }
+    ]);
+
+    // Combine data
+    const data = {
+        project_name: project_name || scanned?.project_name || path.basename(targetDir),
+        description: description || scanned?.description || 'A software project',
+        project_type: project_type || scanned?.project_type || 'web-app',
+        primary_language: primary_language || scanned?.primary_language || 'typescript',
+        frameworks: frameworks || scanned?.frameworks || [],
+        ...dbAndInfra, package_manager, test_framework, max_file_lines
+    };
+
+    data.database = data.database || scanned?.database || 'none';
+    data.uses_docker = typeof data.uses_docker === 'boolean' ? data.uses_docker : (scanned?.uses_docker ?? true);
+    data.cloud = data.cloud || scanned?.cloud || 'none';
+    data.package_manager = data.package_manager || scanned?.package_manager || 'auto-detect';
+    data.test_framework = data.test_framework || scanned?.test_framework || 'auto-detect';
+    data.max_file_lines = data.max_file_lines || scanned?.max_file_lines || '300';
+    data.framework_details = scanned?.framework_details || [];
+    data.scan_evidence = scanned?.scan_evidence || [];
+    data.app_root = scanned?.app_root || '.';
+
+    data.infrastructure = [];
+    if (data.uses_docker) data.infrastructure.push('docker');
+    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
+
+    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
+
+    // Shared entry files are written after the .agent folder is available.
+
+    // Copy .agent folder
+    const { copied, skipped } = copyAgentFolder();
+    if (copied > 0) {
+        console.log(`  ${pc.green('OK')} Copied ${pc.bold('.agent/')} (${copied} file${copied !== 1 ? 's' : ''} added${skipped > 0 ? `, ${skipped} skipped` : ''})`);
+    } else if (skipped > 0) {
+        console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
+    }
+
+
+    const generatedFiles = [
+        ['AGENTS.md', generateSharedAgentsMd(data)],
+        ['CLAUDE.md', generateSharedClaudeMd()],
+        ['GEMINI.md', generateSharedGeminiMd()],
+        [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
+        [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
+        [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc(data)],
+        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()]
+    ];
+
+    for (const [relativePath, content] of generatedFiles) {
+        const wrote = await writeGeneratedFile(relativePath, content, assumeYes);
+        if (wrote) console.log(`  ${pc.green('OK')} Generated ${pc.bold(relativePath)}`);
+        else console.log(`  ${pc.yellow('~')} Skipped ${pc.bold(relativePath)}`);
+    }
+
+    console.log(`\n${pc.bold(pc.green('Done!'))}
+
+  ${pc.bold('Project:')} ${data.project_name}
+  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
+
+  ${pc.bold('Generated:')}
+    - ${pc.bold('AGENTS.md')} shared entry for Codex, Antigravity, and Claude Code
+    - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
+    - ${pc.bold('GEMINI.md')} Antigravity entry
+    - ${pc.bold('.agent/docs/')} scan-based project rules
+    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
+
   ${pc.bold('Next steps:')}
-    1. ${useScan ? `Open ${pc.bold('AGENTS.md')} — paste its content into your AI editor to fill in the placeholders` : `Edit ${pc.bold('AGENTS.md')} and fill in Core Architecture, Coding Conventions, Performance sections`}
-    2. Commit ${pc.bold('AGENTS.md')} to the repo
-    3. Open project in Claude Code / Codex / Antigravity — agent reads AGENTS.md automatically
+    1. Review ${pc.bold('.agent/docs/')} and replace any TODO: refine items with real project facts
+    2. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, and ${pc.bold('.agent/')}
+    3. Open the project in Codex, Antigravity, or Claude Code
+
+  ${pc.bold('Copy this prompt into your AI editor:')}
+${pc.dim('---')}
+Read AGENTS.md and all files under .agent/docs/.
+Scan this repository.
+Update .agent/docs/project.md, .agent/docs/architecture.md, and .agent/docs/conventions.md with factual project-specific rules.
+Do not implement product code.
+Remove TODO: refine only when backed by evidence from the codebase.
+${pc.dim('---')}
 `);
 }
-
-main().catch(err => {
-    console.error(pc.red('\nError during init:'), err);
-    process.exit(1);
-});
+
+main().catch(err => {
+    console.error(pc.red('\nError during init:'), err);
+    process.exit(1);
+});