thachvd-kit 1.0.30 → 1.0.32

package/bin/cli.js

@@ -1,143 +1,59 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const prompts = require('prompts');
-const pc = require('picocolors');
-const packageJson = require('../package.json');
-
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const prompts = require('prompts');
+const pc = require('picocolors');
+const packageJson = require('../package.json');
+
 const sourceDir = path.resolve(__dirname, '..');
 const targetDir = process.cwd();
 const CODEBASE_MEMORY_PACKAGE = 'codebase-memory-mcp';
 const CODEBASE_MEMORY_BINARY = 'codebase-memory-mcp';
 const RTK_INSTALL_COMMAND = 'cargo install --git https://github.com/rtk-ai/rtk --branch master rtk';
-
-// --- 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 = {
-    docker: ["docker-patterns"],
-    aws: ["deployment-procedures", "docker-patterns"],
-    gcp: ["deployment-procedures", "docker-patterns"],
-    azure: ["deployment-procedures", "docker-patterns"],
-    vercel: ["deployment-procedures"],
-};
-
-function resolveSkills(data) {
-    const skills = new Set();
-    const lang = (data.primary_language || "").toLowerCase();
-
-    if (LANG_SKILLS[lang]) {
-        LANG_SKILLS[lang].forEach(s => skills.add(s));
-    }
-
-    (data.frameworks || []).forEach(fw => {
-        const fwLower = fw.toLowerCase();
-        for (const [key, vals] of Object.entries(FRAMEWORK_SKILLS)) {
-            if (fwLower.includes(key)) vals.forEach(s => skills.add(s));
-        }
-    });
-
-    (data.infrastructure || []).forEach(infra => {
-        const infraLower = infra.toLowerCase();
-        for (const [key, vals] of Object.entries(INFRA_SKILLS)) {
-            if (infraLower.includes(key)) vals.forEach(s => skills.add(s));
-        }
-    });
-
-    skills.add("clean-code");
-    skills.add("systematic-debugging");
-
-    return Array.from(skills).sort();
-}
-
-function resolveNativeSkills(data) {
-    return Array.from(new Set([
-        ...resolveSkills(data),
-        'verification-before-completion',
-        'webapp-testing'
-    ])).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']);
-
+
+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 [--yes]
   thachvd-kit setup [--yes]
   thachvd-kit doctor
+  thachvd-kit prompt
   thachvd-kit --version
   thachvd-kit --help
 
 ${pc.bold('Commands:')}
   init      Generate project context files and documentation
-  setup     Install/configure optional MCP and local tooling
+  setup     Install/configure MCP and recommended local tooling
   doctor    Check project context and local integrations
+  prompt    Print the saved project-indexing prompt again
 
 ${pc.bold('Options:')}
   --yes     Overwrite generated files or accept setup defaults
-  --no-setup-mcp Skip MCP setup (legacy init compatibility)
+  --no-setup-mcp  Skip MCP setup (legacy init compatibility)
+  --no-setup-hook Skip the Claude Code Definition-of-Done Stop hook during setup
+  --no-install-rtk Skip auto-installing rtk via cargo during setup
+  --no-index      Skip auto-indexing the repository with codebase-memory-mcp during setup
   --version Show the installed CLI version
   --help    Show this help message
 
@@ -146,7 +62,7 @@ ${pc.bold('What gets generated:')}
   CLAUDE.md   Claude Code entry file that imports AGENTS.md
   GEMINI.md   Antigravity entry file that points to AGENTS.md
   .cursorrules Cursor entry file that points to AGENTS.md
-  .agent/docs/ Project context, architecture, conventions, workflow, and tooling docs
+  .agent/docs/ Project context, architecture, workflow, tooling, and durable onboarding prompt
 
 ${pc.bold('Workflow guide:')}
   Every task               Superpowers     Use the matching native Superpowers skill
@@ -163,734 +79,690 @@ ${pc.bold('Tip:')}
   Run thachvd-kit setup for the integration checklist and doctor to verify it.
 `);
 }
-
-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 = [];
-    const frameworks = (data.frameworks || []).map(f => f.toLowerCase());
-    const lang = (data.primary_language || "").toLowerCase();
-
-    // Frontend
-    const frontendFws = frameworks.filter(f => FRONTEND_FRAMEWORKS.includes(f));
-    if (frontendFws.length > 0) {
-        let feSkills = [];
-        frontendFws.forEach(fw => {
-            feSkills.push(...(FRAMEWORK_SKILLS[fw] || []));
-        });
-        rows.push(["Frontend UI", "frontend-specialist", Array.from(new Set(feSkills)).slice(0, 3).join(", ")]);
-    }
-
-    // Backend
-    let beSkills = [...(LANG_SKILLS[lang] || ["api-design"])];
-    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));
-    if (mobileFws.length > 0) {
-        let mobileSkills = [];
-        mobileFws.forEach(fw => {
-            mobileSkills.push(...(FRAMEWORK_SKILLS[fw] || []));
-        });
-        rows.push(["Mobile/Desktop", "mobile-developer", Array.from(new Set(mobileSkills)).slice(0, 3).join(", ")]);
-    }
-
-    // DevOps
-    if (data.uses_docker || data.cloud !== "none") {
-        rows.push(["DevOps/Infra", "devops-engineer", "docker-patterns, deployment-procedures"]);
-    }
-
-    rows.push(["Debug", "debugger", "systematic-debugging"]);
-    rows.push(["Security", "security-auditor", "vulnerability-scanner"]);
-    rows.push(["Planning", "project-planner", "brainstorming, plan-writing"]);
-
    return rows;
-}
-// --- File Generators ---
-
+
+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 -->'
+    };
+}
+// --- File Generators ---
+
 function generateSharedAgentsMd(data) {
     return `# AGENTS.md
 
 Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
-
-## 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.
+
+## 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. Read \`.agent/docs/tooling.md\` when the task needs MCP, RTK, or browser verification.
 
 If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
@@ -909,208 +781,230 @@ Superpowers is the primary workflow backend. Use its native skills when availabl
 Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the scope and verification before editing. If the scope grows, switch to the full Superpowers flow.
 
 If Superpowers is unavailable, follow the plain-language flow in \`.agent/docs/workflow.md\`; do not expect this kit to provide a second copy of the workflow engine.
-
-## Rules
-
-- 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.
+
+## Rules
+
+- 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.
 - **MCP First**: Prioritize \`codebase-memory-mcp\` for symbols, call paths, architecture, and impact; use \`context7\` for API/docs queries and \`playwright\` for browser/UI verification. Fall back to normal file search when an integration is unavailable.
-- 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\`.
-
+- Prefer \`rtk\` by default for verbose shell commands such as \`rtk git status\`, \`rtk npm test\`, and \`rtk git log\`. Run the underlying command directly only when RTK is unavailable or incompatible.
+- 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\`.
+
 ## Shared Knowledge
 
 - Project context: \`.agent/docs/\`
 - Tooling setup: \`.agent/docs/tooling.md\`
 - Superpowers: installed through the AI client's official plugin surface
-- RTK: optional local CLI for compact command output
+- RTK: recommended local CLI for compact command output
 - Antigravity and Cursor entry rules: \`GEMINI.md\` and \`.cursorrules\`
 `;
 }
-
-function generateSharedClaudeMd() {
-    return `@AGENTS.md
-
-## Claude Code
-
-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
-
-Antigravity entry file for this project.
-
-Read AGENTS.md first, then follow the shared docs under .agent/docs/.
-`;
-}
-
-function generateSharedCursorrules(data) {
+
+function generateIndexProjectPrompt() {
+    return `# Project Indexing Prompt
+
+Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
+Use Superpowers for the workflow and use codebase-memory MCP for structural code discovery when available.
+Ask me what this project does and any important conventions I want preserved.
+Then scan this repository and refine the generated context docs with factual rules.
+Do not implement product code during onboarding.
+`;
+}
+
+function printProjectPrompt() {
+    const promptPath = path.join(targetDir, '.agent', 'docs', 'index-project-prompt.md');
+    if (!fs.existsSync(promptPath)) {
+        console.error(pc.yellow('No saved project prompt found. Run thachvd-kit init first.'));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(fs.readFileSync(promptPath, 'utf8'));
+}
+
+function generateSharedClaudeMd() {
+    return `@AGENTS.md
+
+## Claude Code
+
+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
+
+Antigravity entry file for this project.
+
+Read AGENTS.md first, then follow the shared docs under .agent/docs/.
+`;
+}
+
+function generateSharedCursorrules(data) {
     return `# Cursor Rules
-
-This repository uses AGENTS.md as the shared cross-agent entry file. Follow the instructions in AGENTS.md and keep Cursor-specific notes here only when they cannot apply to Codex, Antigravity, or Claude Code.
-
-Read AGENTS.md first, then follow the shared docs under .agent/docs/.
-
----
-
+
+This repository uses AGENTS.md as the shared cross-agent entry file. Follow the instructions in AGENTS.md and keep Cursor-specific notes here only when they cannot apply to Codex, Antigravity, or Claude Code.
+
+Read AGENTS.md first, then follow the shared docs under .agent/docs/.
+
+---
+
 ${generateSharedAgentsMd(data).trimEnd()}
 `;
-}
-
-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 isPython = primaryLang === 'python';
-    const isGo = primaryLang === 'go';
-    const isRust = primaryLang === 'rust';
-    const isPhp = primaryLang === 'php';
-
-    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) {
-        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) {
-            dev = 'bin/cake server';
-            lint = './vendor/bin/phpcs';
-        } else if (isSymfony) {
-            dev = 'bin/console server:run';
-            lint = './vendor/bin/phpcs';
-        } else if (isCodeIgniter) {
-            dev = 'php spark serve';
-            lint = './vendor/bin/phpcs';
-        } else {
-            dev = 'php artisan serve';
-            lint = 'php artisan pint';
-        }
-    }
-
-    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`;
-
-    return { install, dev, build, test, lint };
-}
-
-function generateProjectDoc(data) {
-    const commands = resolveCommands(data);
-    const evidence = (data.scan_evidence || []).length > 0
-        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
-        : '- TODO: refine scan evidence by inspecting the project.';
-
-    return `# Project Rules
-
-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}\`
-
+}
+
+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 isPython = primaryLang === 'python';
+    const isGo = primaryLang === 'go';
+    const isRust = primaryLang === 'rust';
+    const isPhp = primaryLang === 'php';
+
+    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) {
+        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) {
+            dev = 'bin/cake server';
+            lint = './vendor/bin/phpcs';
+        } else if (isSymfony) {
+            dev = 'bin/console server:run';
+            lint = './vendor/bin/phpcs';
+        } else if (isCodeIgniter) {
+            dev = 'php spark serve';
+            lint = './vendor/bin/phpcs';
+        } else {
+            dev = 'php artisan serve';
+            lint = 'php artisan pint';
+        }
+    }
+
+    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`;
+
+    return { install, dev, build, test, lint };
+}
+
+function generateProjectDoc(data) {
+    const commands = resolveCommands(data);
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine scan evidence by inspecting the project.';
+
+    return `# Project Rules
+
+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}\`
+
 ## Available Integrations
-
+
 Use these integrations when available. Run thachvd-kit doctor to check the current machine.
-
-| MCP | When to Use |
-|-----|-------------|
+
+| MCP | When to Use |
+|-----|-------------|
 | \`codebase-memory-mcp\` | Explore symbols, trace call chains, architecture, and impact |
-| \`context7\` | Look up library/framework docs, API signatures, migration guides |
+| \`context7\` | Look up library/framework docs, API signatures, migration guides |
 | \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
-| \`rtk\` | Reduce noisy output from git, tests, builds, and package commands |
-
-> Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
-
+| \`rtk\` | Recommended proxy for noisy git, tests, builds, and package commands |
+
+> Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
+
 ## 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.
-- For UI/web changes, prioritize using Playwright MCP to automatically verify client-side behavior and capture screenshots.
-- Do not claim completion without verification 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.
+- For UI/web changes, prioritize using Playwright MCP to automatically verify client-side behavior and capture screenshots.
+- Do not claim completion without verification evidence.
+`;
+}
+
 function generateWorkflowDoc() {
     return `# Agent Workflow
 
@@ -1150,89 +1044,8 @@ Use it only for one-file, unambiguous changes with no behavior, API, schema, sec
 - Update project.md when stack, scripts, or test tooling changes.
 - Keep AGENTS.md concise and put project-specific detail under .agent/docs/.
 `;
-    /* Legacy workflow text below remains unreachable for source compatibility. */
-    return `# Agent Workflow
-
-## Before Every Task
-
-1. Read AGENTS.md.
-2. Read .agent/docs/project.md.
-3. Use the matching native Superpowers skill for the task.
-4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
-5. Use codebase-memory MCP for structural discovery when available, then verify the actual files before editing.
-
-## Route Matrix
+}
 
-| Situation | Command | Workflow / gate |
-|---|---|---|
-| Question or analysis only | direct answer | no edits |
-| One obvious local fix | fast path | inspect -> edit -> focused verify |
-| Bug, regression, failing test, or unknown error | systematic-debugging | reproduce -> root cause -> regression test -> fix -> verify |
-| Research request | direct research | evidence report, no edits |
-| New behavior, multi-file change, or unclear scope | brainstorming -> writing-plans -> executing-plans | explicit approval before implementation |
-| Pre-merge review | requesting-code-review | blocking findings resolved |
-| Several specialist domains | subagent-driven-development | task review and final review |
-
-If a task is not clearly simple, use the standard flow. Never use the fast path for behavior, API, schema, security, CI, dependency, workflow, or release changes.
-
-## Superpowers Skills
-
-- Use brainstorming for unclear requirements.
-- Use using-git-worktrees and writing-plans before non-trivial implementation.
-- Use test-driven-development, executing-plans or subagent-driven-development during implementation.
-- Use systematic-debugging for bugs and requesting-code-review before completion.
-- thachvd-kit does not copy or replace Superpowers skills.
-- Do not load skill bodies by default.
-- Load a skill when the user mentions it, the task clearly matches its SKILL.md description, or .agent/docs/project.md routes the task to it.
-- Use explicit skill names in prompts for predictable behavior, for example $webapp-testing or $clean-code.
-- Run thachvd-kit --help to see common workflow and skill recommendations.
-
-## Implementation Flow
-
-For \`/forge-fast\` fixes, state the fast-path decision before editing:
-
-\`\`\`text
-FAST_PATH: simple-fix
-REASON: [why Spec/Plan/Review are not needed]
-SCOPE: [file or narrow area]
-\`\`\`
-
-Then:
-
-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 (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
-6. Summarize changed files and verification evidence.
-
-For bugs, use \`/forge-debug\` with Superpowers' \`systematic-debugging\` when available, otherwise the matching local skill, plus the \`debugger\` agent and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
-
-For features or refactors, prefer the Superpowers chain when available: brainstorm/spec -> worktree -> detailed plan -> approval -> TDD/task execution -> per-task review -> final review -> finish branch. Otherwise use the local gated flow defined in AGENTS.md (spec -> plan -> implement -> review). Steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory review gate.
-
-## Definition of Done (feature or refactor)
-
-A feature/refactor task is only complete when all of the following hold — not when code compiles or tests pass:
-
-The Spec checkbox may be skipped only when the documented \`/forge-fast\` protocol is stated and its criteria are met.
-
-- [ ] \`.agent/workflows/spec.md\` exit criteria met (or explicitly skipped as a trivial/self-contained change)
-- [ ] \`.agent/workflows/plan.md\` produced a plan file, approved by the user
-- [ ] Tests added/updated for the changed behavior and passing
-- [ ] \`.agent/workflows/review.md\` five-axis review completed with all 🔴 BLOCKING items resolved or accepted with rationale
-- [ ] Changed files and verification evidence summarized to the user
-
-Do not report a feature/refactor task as done if any box above is unchecked — say explicitly which gate is still open.
-
-## 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.
-`;
-}
-
 function generateGettingStartedDoc() {
     return `# Getting Started
 
@@ -1241,8 +1054,8 @@ thachvd-kit creates project context. Superpowers owns the development workflow.
 ## Setup
 
 1. Run \`thachvd-kit init\` in the repository.
-2. Install Superpowers from the official plugin surface for the AI client you use.
-3. Run \`thachvd-kit setup\` to configure codebase-memory MCP and print integration guidance.
+2. Open or print \`.agent/docs/index-project-prompt.md\` with \`thachvd-kit prompt\`.
+3. Install Superpowers and RTK, then run \`thachvd-kit setup\`.
 4. Run \`thachvd-kit doctor\` and restart the AI client.
 
 ## Standard Flow
@@ -1264,124 +1077,26 @@ Use \`systematic-debugging\`: reproduce the symptom, inspect the path with codeb
 
 Use a fast path only for one-file, unambiguous changes with no behavior or contract change. State the scope and verification before editing. If the scope expands, return to brainstorming and writing-plans.
 `;
-    /* Legacy text below remains unreachable for source compatibility and is removed in a later major cleanup. */
-    return `# Getting Started With This Kit
-
-Read this after \`thachvd-kit init\`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
-
-## Forge Command Map
-
-| Client | Task | Fast | Debug | Research | Review |
-|---|---|---|---|---|---|
-| Codex | \`$forge-task\` | \`$forge-fast\` | \`$forge-debug\` | \`$forge-research\` | \`$forge-review\` |
-| Antigravity | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` |
-| Claude Code | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` |
-| Cursor | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` |
-
-Forge commands accept free-form text after the command and continue the selected workflow in the same turn. Plain questions remain normal chat; edit requests without a command are implicitly routed as \`forge-task\`.
-
-Forge is a routing layer. For feature/refactor work, prefer native Superpowers skills when available: brainstorming, using-git-worktrees, writing-plans, subagent-driven-development or executing-plans, test-driven-development, requesting-code-review, and finishing-a-development-branch. If Superpowers is not installed, use the matching \`.agent/skills/\` and \`.agent/workflows/\` fallback; do not maintain a competing duplicate methodology. Install the full execution backend from https://github.com/obra/superpowers#quickstart.
-
-Codex Forge skills live in \`~/.codex/skills/forge-*/SKILL.md\`. Antigravity Forge workflows live in \`.agent/workflows/forge-*.md\`. Claude Code Forge commands live in \`.claude/commands/forge-*.md\`. Cursor Forge commands live in \`.cursor/commands/forge-*.md\`.
-
-## Start Every Task With Forge
-
-Use the matching Forge command before editing whenever the request is not a simple question. \`forge-task\` must route internally and continue; it must not stop by asking the member to type a second command.
-
-\`\`\`text
-ROUTE: question | fast | feature | bug | research | review | multi-domain
-WORKFLOW: [exact .agent/workflows/<name>.md file]
-SKILLS: [matching skills, or none]
-AGENTS: [matching specialist agents, or none]
-GATE: fast-path | standard | human-approval
-BACKEND: superpowers-native | forge-fallback
-ACTION: [what the agent is doing next in this turn]
-\`\`\`
-
-A workflow is the process and its gates. A skill is the method or checklist. An agent is the specialist role. Chat alone is not a route: the member must select the route and invoke the matching workflow or explicitly choose the question path.
-
-## Route Matrix
-
-| Situation | Command | Gate | Required next step |
-|---|---|---|---|
-| Explain, inspect, or brainstorm only | direct answer or \`/brainstorm\` | none | no code until the request becomes actionable |
-| One obvious local fix | \`/forge-fast <request>\` | fast-path | inspect -> edit -> focused verify |
-| New behavior, multi-file change, unclear scope, or >~30 min | \`/forge-task <request>\` | standard | route -> research/spec/plan -> approval when required -> continue |
-| Bug, regression, failing test, or unknown error | \`/forge-debug <symptom>\` | bug | reproduce -> isolate -> regression test -> fix -> verify |
-| Research request | \`/forge-research <question>\` | research | evidence report, no edits |
-| Pre-merge or independent review | \`/forge-review\` | review | five-axis review; resolve blocking findings |
-| Frontend + backend + data/security together | \`/orchestrate\` | standard | plan -> approval -> specialist work -> integration verify |
-
-## Standard Feature Flow
-
-The gated sequence is Spec -> Plan -> Implement -> Review. \`/forge-task\` manages this sequence internally and pauses only at the explicit user approval gate before implementation.
-
-The plan is a gate, not a suggestion. Do not start product-code implementation before explicit approval. Load only the relevant specialist agent and skills, such as \`$frontend-design\`, \`$api-design\`, or \`$webapp-testing\`.
-
-## Bug Fix Flow
-
-Use \`/forge-debug <symptom>\`, not the feature flow, when something is failing or the root cause is unknown:
-
-1. Capture the exact symptom, environment, reproduction, and expected result.
-2. Inspect the relevant code path with MCP/codegraph when available.
-3. Form and test a small number of hypotheses; do not patch by guesswork.
-4. Add or update a regression test that fails before the fix when practical.
-5. Make the smallest root-cause fix.
-6. Run focused tests, then broader verification when the blast radius is shared.
-7. Use \`/review\` when the fix touches multiple files, contracts, security, or release behavior.
-
-Load Superpowers' \`systematic-debugging\` when available, otherwise the matching local skill, plus the \`debugger\` agent and \`testing-patterns\` for this route.
-
-## Simple Fast Path
-
-Use \`/forge-fast <request>\` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
-
-\`\`\`text
-FAST_PATH: simple-fix
-REASON: [why Spec/Plan/Review are not needed]
-SCOPE: [file or narrow area]
-\`\`\`
-
-This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route internally through \`forge-task\`.
-
-## Command And Skill Map
-
-- \`/brainstorm\`: clarify intent and tradeoffs; no code.
-- \`forge-research\`: evidence-based codebase/technical/domain research; no product-code edits.
-- \`/plan\`: create an approved implementation plan; no code before approval.
-- \`/enhance\` or \`/create\`: implement an approved feature with the relevant specialist agent.
-- \`forge-debug\`: systematic root-cause investigation and regression protection.
-- \`/test\`: add or run tests and assess coverage.
-- \`/review\`: five-axis review before completion or merge.
-- \`$clean-code\` and \`$verification-before-completion\`: default implementation hygiene.
-- \`$webapp-testing\`: browser/UI verification; use Playwright when available.
-
-## Enforcement
-
-Claude Code has a project Stop hook in \`.claude/settings.json\` for standard feature/refactor work. An explicit \`FAST_PATH: simple-fix\` is accepted only when the simple criteria are met; it still requires verification. Codex, Antigravity, and Cursor use the same written rules through \`AGENTS.md\`, \`.cursorrules\`, and \`.agent/rules/GEMINI.md\`.
+}
 
-Full details live in \`AGENTS.md\`, \`.agent/docs/workflow.md\`, and the matching file under \`.agent/workflows/\`.
-`;
+function resolveToolingSetup(data) {
+    const primaryLang = data.primary_language || 'javascript';
+    const packageManager = data.package_manager || 'npm';
+    const isPython = primaryLang === 'python';
+    const runner = packageManager === 'pnpm'
+        ? 'pnpm dlx'
+        : packageManager === 'yarn'
+            ? 'yarn dlx'
+            : packageManager === 'bun'
+                ? 'bunx'
+                : 'npx';
+    const playwrightCommand = isPython
+        ? 'pip install playwright && playwright install chromium'
+        : `${runner} playwright install`;
+
+    return { runner, playwrightCommand };
 }
 
-function resolveToolingSetup(data) {
-    const primaryLang = data.primary_language || 'javascript';
-    const packageManager = data.package_manager || 'npm';
-    const isPython = primaryLang === 'python';
-    const runner = packageManager === 'pnpm'
-        ? 'pnpm dlx'
-        : packageManager === 'yarn'
-            ? 'yarn dlx'
-            : packageManager === 'bun'
-                ? 'bunx'
-                : 'npx';
-    const playwrightCommand = isPython
-        ? 'pip install playwright && playwright install chromium'
-        : `${runner} playwright install`;
-
-    return { runner, playwrightCommand };
-}
-
 function generateToolingDoc(data) {
     const { runner, playwrightCommand } = resolveToolingSetup(data);
 
@@ -1411,10 +1126,11 @@ Use \`codebase-memory-mcp\` for symbol search, call paths, architecture, and imp
 
 ## RTK
 
-RTK is optional command-output compression, not a workflow engine.
+RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands.
 
 - Install: \`cargo install --git https://github.com/rtk-ai/rtk --branch master rtk\`
-- Prefer it for verbose git, test, build, package, and container commands when available.
+- Examples: \`rtk git status\`, \`rtk npm test\`, \`rtk git log\`.
+- If it is unavailable, run the underlying command directly.
 
 ## Playwright
 
@@ -1422,368 +1138,33 @@ RTK is optional command-output compression, not a workflow engine.
 - Browser install: \`${playwrightCommand}\`
 - Use the project's existing Playwright scripts when available.
 `;
-    /* Legacy tooling text below remains unreachable for source compatibility. */
-
-    return `# Optional Tooling
-
-This kit keeps tool setup explicit. Do not assume these tools are available until you verify them in the current environment.
-
-## Playwright
-
-Use Playwright for browser and UI verification when a task touches web behavior.
-
-- Check availability: \`${runner} playwright --version\`
-- Install browsers: \`${playwrightCommand}\`
-- Codex MCP CLI setup: \`codex mcp add playwright -- playwright-mcp\`
-- Auto setup: \`thachvd-kit\`
-- Kit helper: \`python .agent/skills/webapp-testing/scripts/playwright_runner.py <url> --screenshot\`
-
-If the project already has Playwright configured, prefer the project's existing scripts.
-
-Codex \`config.toml\` example:
-
-\`\`\`toml
-[mcp_servers.context7]
-command = "context7-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-
-[mcp_servers.filesystem]
-command = "npx"
-args = ["-y", "@modelcontextprotocol/server-filesystem", "<projectPath>"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-
-[mcp_servers.playwright]
-command = "playwright-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-\`\`\`
-
-## Codegraph
-
-Use codegraph for codebase exploration when the environment exposes it. The index is local state and should not be committed.
-
-- Check for an index: look for \`.codegraph/\`
-- Check CLI availability: \`codegraph --help\`
-- Install CLI if needed: \`npm install -g @colbymchenry/codegraph\`
-- Codex MCP CLI setup: \`codex mcp add codegraph -- codegraph serve --mcp\`
-- Auto setup: \`thachvd-kit\`
-- If your Codex environment provides the codegraph CLI, run its project indexing step from the repository root.
-- Keep \`.codegraph/\` ignored in git.
-
-Codex \`config.toml\` example:
-
-\`\`\`toml
-[mcp_servers.codegraph]
-command = "codegraph"
-args = ["serve", "--mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-\`\`\`
-
-Codex reads MCP servers from \`~/.codex/config.toml\` by default. For repo-local setup, use \`.codex/config.toml\`; Codex loads project config only for trusted projects.
-
-Gemini CLI / Antigravity \`mcp_config.json\` example:
-
-\`\`\`json
-{
-  "mcpServers": {
-    "codegraph": {
-      "command": "codegraph",
-      "args": ["serve", "--mcp"]
-    },
-    "context7": {
-      "command": "context7-mcp"
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "command": "playwright-mcp"
-    }
-  }
-}
-\`\`\`
-
-Common local paths:
-
-- Gemini CLI: \`~/.gemini/config/mcp_config.json\`
-- Antigravity IDE: \`~/.gemini/antigravity-ide/mcp_config.json\`
-- Older Antigravity setups may use \`~/.gemini/antigravity/mcp_config.json\`
-
-Claude Code user config example:
-
-\`\`\`json
-{
-  "mcpServers": {
-    "codegraph": {
-      "type": "stdio",
-      "command": "codegraph",
-      "args": ["serve", "--mcp"]
-    },
-    "context7": {
-      "type": "stdio",
-      "command": "context7-mcp"
-    },
-    "filesystem": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "type": "stdio",
-      "command": "playwright-mcp"
-    }
-  }
-}
-\`\`\`
-
-Common local path:
-
-- Claude Code: \`~/.claude.json\` or \`~/.claude/settings.json\`
-
-## Native Skill Folders
-
-The shared kit skills live in \`.agent/skills/\`. Antigravity reads that folder directly. Codex shows skills from \`~/.codex/skills/\` in the \`$\` menu. Claude Code reads project skills from \`.claude/skills/\`.
-
-- Codex global skills: \`~/.codex/skills/\` — installed by \`thachvd-kit init\`, visible in Codex \`$\` menu
-- Claude Code project skills: \`.claude/skills/\`
-- Antigravity: reads \`.agent/skills/\` directly (no copy needed)
-- Keep \`.agent/skills/\` as the full shared source of truth committed with the repo.
-- Do not commit \`~/.codex/skills/\`; it is local user state.
-
-Recommended candidates to copy first:
-
-- \`clean-code\`
-- \`systematic-debugging\`
-- \`verification-before-completion\`
-- Stack-specific skills listed in \`.agent/docs/project.md\`
-`;
-}
-
-// --- 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;
-
-    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;
-            }
-            if (entry.isDirectory()) {
-                copyDir(srcPath, destPath);
-            } else {
-                fs.copyFileSync(srcPath, destPath);
-                copied++;
-            }
-        }
-    }
-
-    copyDir(srcAgent, destAgent);
-    return { copied, skipped: 0 };
-}
-
-function copySelectedSkillFolders(data, assumeYes) {
-    const srcSkills = path.join(sourceDir, '.agent', 'skills');
-    if (!fs.existsSync(srcSkills)) return { copied: 0, skipped: 0, missing: 0, skills: [] };
-
-    const selectedSkills = resolveNativeSkills(data);
-
-    // ~/.codex/skills/ — global Codex user skills dir, always visible in the $ menu
-    const codexSkillsDir = homePath('.codex', 'skills');
-    // .claude/skills/ — project-level Claude Code skills
-    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
-
-    const destinations = [claudeSkillsDir];
-    if (codexSkillsDir) destinations.push(codexSkillsDir);
-
-    let copied = 0;
-    let missing = 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);
-            if (entry.isDirectory()) {
-                copyDir(srcPath, destPath);
-            } else {
-                fs.mkdirSync(path.dirname(destPath), { recursive: true });
-                fs.copyFileSync(srcPath, destPath);
-                copied++;
-            }
-        }
-    }
-
-    for (const skill of selectedSkills) {
-        const srcSkill = path.join(srcSkills, skill);
-        if (!fs.existsSync(srcSkill)) {
-            missing++;
-            continue;
-        }
-        for (const destSkills of destinations) {
-            copyDir(srcSkill, path.join(destSkills, skill));
-        }
-    }
-
-    return { copied, skipped: 0, missing, skills: selectedSkills };
-}
-
-function copyCodexPrompts() {
-    const srcPrompts = path.join(sourceDir, 'prompts');
-    const codexPromptsDir = homePath('.codex', 'prompts');
-    if (!fs.existsSync(srcPrompts) || !codexPromptsDir) {
-        return { copied: 0, prompts: [] };
-    }
-
-    let copied = 0;
-    const prompts = [];
-    fs.mkdirSync(codexPromptsDir, { recursive: true });
-    for (const entry of fs.readdirSync(srcPrompts, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-        fs.copyFileSync(path.join(srcPrompts, entry.name), path.join(codexPromptsDir, entry.name));
-        copied++;
-        prompts.push(path.basename(entry.name, '.md'));
-    }
-    return { copied, prompts };
-}
-
-function copyClientWorkflowCommands() {
-    const srcPrompts = path.join(sourceDir, 'prompts');
-    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
-    const cursorCommandsDir = path.join(targetDir, '.cursor', 'commands');
-    if (!fs.existsSync(srcPrompts)) {
-        return { claude: 0, cursor: 0, prompts: [] };
-    }
-
-    let claude = 0;
-    let cursor = 0;
-    const prompts = [];
-    for (const entry of fs.readdirSync(srcPrompts, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-        const name = path.basename(entry.name, '.md');
-        const sourcePath = path.join(srcPrompts, entry.name);
-        const sourceContent = fs.readFileSync(sourcePath, 'utf8');
-        const cursorContent = sourceContent.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
-        fs.mkdirSync(path.join(claudeSkillsDir, name), { recursive: true });
-        fs.copyFileSync(sourcePath, path.join(claudeSkillsDir, name, 'SKILL.md'));
-        fs.mkdirSync(cursorCommandsDir, { recursive: true });
-        fs.writeFileSync(path.join(cursorCommandsDir, entry.name), cursorContent, 'utf8');
-        claude++;
-        cursor++;
-        prompts.push(name);
-    }
-    return { claude, cursor, prompts };
 }
 
-function stripFrontmatter(content) {
-    return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trimStart();
-}
-
-function copyForgeCommands() {
-    const srcCommands = path.join(sourceDir, 'commands');
-    const codexSkillsDir = homePath('.codex', 'skills');
-    if (!fs.existsSync(srcCommands)) {
-        return { antigravity: 0, claude: 0, cursor: 0, codex: 0, commands: [] };
-    }
-
-    const destinations = {
-        antigravity: path.join(targetDir, '.agent', 'workflows'),
-        claude: path.join(targetDir, '.claude', 'commands'),
-        cursor: path.join(targetDir, '.cursor', 'commands')
-    };
-
-    for (const commandName of REMOVED_FORGE_COMMANDS) {
-        const filename = `${commandName}.md`;
-        for (const destination of Object.values(destinations)) {
-            const commandPath = path.join(destination, filename);
-            if (fs.existsSync(commandPath)) fs.rmSync(commandPath, { force: true });
+async function writeGeneratedFile(relativePath, content, assumeYes) {
+    const outputPath = path.join(targetDir, relativePath);
+    const exists = fs.existsSync(outputPath);
+    if (exists && !assumeYes) {
+        const response = await prompts({
+            type: 'confirm',
+            name: 'overwrite',
+            message: `File ${pc.bold(relativePath)} already exists. Do you want to overwrite it?`,
+            initial: false
+        });
+        if (response.overwrite === undefined) {
+            console.log(pc.yellow('\nCancelled.'));
+            process.exit(130);
         }
-        if (codexSkillsDir) {
-            const codexSkillPath = path.join(codexSkillsDir, commandName);
-            if (fs.existsSync(codexSkillPath)) fs.rmSync(codexSkillPath, { recursive: true, force: true });
-        }
-    }
-
-    let antigravity = 0;
-    let claude = 0;
-    let cursor = 0;
-    let codex = 0;
-    const commands = [];
-
-    for (const commandName of FORGE_COMMANDS) {
-        const filename = `${commandName}.md`;
-        const sourcePath = path.join(srcCommands, filename);
-        if (!fs.existsSync(sourcePath)) continue;
-        const sourceContent = fs.readFileSync(sourcePath, 'utf8');
-        const body = stripFrontmatter(sourceContent);
-
-        fs.mkdirSync(destinations.antigravity, { recursive: true });
-        fs.copyFileSync(sourcePath, path.join(destinations.antigravity, filename));
-        antigravity++;
-
-        fs.mkdirSync(destinations.claude, { recursive: true });
-        fs.copyFileSync(sourcePath, path.join(destinations.claude, filename));
-        claude++;
-
-        fs.mkdirSync(destinations.cursor, { recursive: true });
-        fs.writeFileSync(path.join(destinations.cursor, filename), body, 'utf8');
-        cursor++;
-
-        if (codexSkillsDir) {
-            const skillDir = path.join(codexSkillsDir, commandName);
-            fs.mkdirSync(skillDir, { recursive: true });
-            const skillBody = body.replace(/\$ARGUMENTS/g, 'the request supplied with this skill');
-            fs.writeFileSync(
-                path.join(skillDir, 'SKILL.md'),
-                `---\nname: ${commandName}\ndescription: ${sourceContent.match(/^description:\s*(.+)$/m)?.[1] || `Run ${commandName}`}\n---\n\nThis skill is invoked as $${commandName}. Treat the user's text supplied with the skill as the request.\n\n${skillBody}`,
-                'utf8'
-            );
-            codex++;
-        }
-
-        commands.push(commandName);
+        if (!response.overwrite) return false;
     }
 
-    return { antigravity, claude, cursor, codex, commands };
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, content, 'utf8');
+    return true;
 }
-
-async function writeGeneratedFile(relativePath, content, assumeYes) {
-    const outputPath = path.join(targetDir, relativePath);
-    const exists = fs.existsSync(outputPath);
-    if (exists && !assumeYes) {
-        const response = await prompts({
-            type: 'confirm',
-            name: 'overwrite',
-            message: `File ${pc.bold(relativePath)} already exists. Do you want to overwrite it?`,
-            initial: false
-        });
-        if (response.overwrite === undefined) {
-            console.log(pc.yellow('\nCancelled.'));
-            process.exit(130);
-        }
-        if (!response.overwrite) return false;
-    }
-
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-    fs.writeFileSync(outputPath, content, 'utf8');
-    return true;
-}
-
+
 function homePath(...parts) {
-    const home = process.env.USERPROFILE || process.env.HOME;
-    return home ? path.join(home, ...parts) : null;
+    const home = process.env.USERPROFILE || process.env.HOME;
+    return home ? path.join(home, ...parts) : null;
 }
 
 function printSuperpowersInstallGuide() {
@@ -1810,23 +1191,26 @@ function runDoctor() {
 
     const tools = [
         [CODEBASE_MEMORY_BINARY, `npm install -g ${CODEBASE_MEMORY_PACKAGE}`],
-        ['rtk', RTK_INSTALL_COMMAND],
+        ['rtk', `recommended: ${RTK_INSTALL_COMMAND}`],
         ['agy', 'install Antigravity before running its Superpowers plugin command'],
         ['claude', 'install Claude Code before installing its Superpowers plugin'],
         ['codex', 'install Codex before using its Superpowers plugin']
     ];
-    console.log(`\n${pc.bold('Local integrations')}`);
+    console.log(`\n${pc.bold('Local integrations (RTK recommended)')}`);
     for (const [binary, hint] of tools) {
         const ok = commandExists(binary);
         console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${binary}${ok ? '' : ` - ${hint}`}`);
     }
 
     console.log(`\n${pc.bold('Next step')}`);
-    console.log('  Run thachvd-kit setup to configure MCP and print client-specific Superpowers setup.');
+    console.log('  Run thachvd-kit prompt to print the saved project-indexing prompt.');
 }
 
 async function runSetup(args) {
     const skipMcpSetup = args.includes('--no-setup-mcp');
+    const skipHookSetup = args.includes('--no-setup-hook');
+    const skipRtkInstall = args.includes('--no-install-rtk');
+    const skipIndex = args.includes('--no-index');
     console.log(pc.bold(pc.cyan('thachvd-kit setup')));
     printSuperpowersInstallGuide();
     if (!skipMcpSetup) {
@@ -1835,23 +1219,35 @@ async function runSetup(args) {
             const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
             console.log(`  ${marker} ${result.message}`);
         }
+        if (!skipIndex) {
+            const indexResult = indexRepository();
+            const marker = indexResult.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${marker} ${indexResult.message}`);
+        }
     }
-    console.log(`\n${pc.bold('RTK')}`);
-    if (commandExists('rtk')) {
-        console.log(`  ${pc.green('OK')} rtk already installed`);
-    } else {
-        console.log(`  ${pc.yellow('WARN')} rtk is not installed; run: ${RTK_INSTALL_COMMAND}`);
+    if (!skipHookSetup) {
+        console.log(`\n${pc.bold('Claude Code Definition-of-Done hook')}`);
+        const claudeProjectSettings = path.join(targetDir, '.claude', 'settings.json');
+        const result = mergeClaudeProjectHooks(claudeProjectSettings);
+        const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
+        console.log(`  ${marker} ${result.message}`);
+        console.log('  This hook only checks for plan/review/verification evidence; it never prescribes which skill produces it.');
     }
+    console.log(`\n${pc.bold('RTK (recommended)')}`);
+    const rtkResult = ensureRtkInstalled(!skipRtkInstall);
+    const rtkMarker = rtkResult.ok ? pc.green('OK') : pc.yellow('WARN');
+    console.log(`  ${rtkMarker} ${rtkResult.message}`);
     console.log('\nRestart your AI client after installing plugins or changing MCP configuration.');
+    console.log('Your onboarding prompt is saved at .agent/docs/index-project-prompt.md. Run thachvd-kit prompt to print it again.');
 }
 
 function commandExists(command) {
-    const checker = process.platform === 'win32' ? 'where' : 'command';
-    const args = process.platform === 'win32' ? [command] : ['-v', command];
-    const result = spawnSync(checker, args, { encoding: 'utf8', shell: process.platform !== 'win32' });
-    return result.status === 0;
-}
-
+    const checker = process.platform === 'win32' ? 'where' : 'command';
+    const args = process.platform === 'win32' ? [command] : ['-v', command];
+    const result = spawnSync(checker, args, { encoding: 'utf8', shell: process.platform !== 'win32' });
+    return result.status === 0;
+}
+
 function ensureGlobalNpmPackage(binaryName, packageName, install = false) {
     if (commandExists(binaryName)) {
         return { ok: true, message: `${binaryName} already installed` };
@@ -1860,113 +1256,149 @@ function ensureGlobalNpmPackage(binaryName, packageName, install = false) {
         return { ok: false, message: `${binaryName} is missing; run: npm install -g ${packageName}` };
     }
     if (!commandExists('npm')) {
-        return { ok: false, message: `npm not found; run: npm install -g ${packageName}` };
-    }
-    const result = spawnSync('npm', ['install', '-g', packageName], {
-        encoding: 'utf8',
-        stdio: 'pipe'
-    });
-    if (result.status !== 0) {
-        return { ok: false, message: `failed to install ${binaryName}; run: npm install -g ${packageName}` };
-    }
-    return { ok: true, message: `installed ${binaryName}` };
-}
-
+        return { ok: false, message: `npm not found; run: npm install -g ${packageName}` };
+    }
+    const result = spawnSync('npm', ['install', '-g', packageName], {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `failed to install ${binaryName}; run: npm install -g ${packageName}` };
+    }
+    return { ok: true, message: `installed ${binaryName}` };
+}
+
 function ensureCodebaseMemoryCli(install = false) {
     return ensureGlobalNpmPackage(CODEBASE_MEMORY_BINARY, CODEBASE_MEMORY_PACKAGE, install);
 }
-
-function readJsonFile(filePath) {
-    if (!fs.existsSync(filePath)) return {};
-    try {
-        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    } catch {
-        return null;
-    }
-}
-
-function writeJsonFile(filePath, data) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
-}
-
-function mergeMcpJson(filePath, withType = false) {
-    const data = readJsonFile(filePath);
-    if (data === null) {
-        return { ok: false, message: `${filePath} is not valid JSON; skipped` };
-    }
-    data.mcpServers = data.mcpServers || {};
+
+function ensureRtkInstalled(install = false) {
+    if (commandExists('rtk')) {
+        return { ok: true, message: 'rtk already installed' };
+    }
+    if (!install) {
+        return { ok: false, message: `rtk is missing; run: ${RTK_INSTALL_COMMAND}` };
+    }
+    if (!commandExists('cargo')) {
+        return { ok: false, message: `cargo not found; install Rust, then run: ${RTK_INSTALL_COMMAND}` };
+    }
+    console.log(pc.dim('  Installing rtk via cargo (compiles from source; this can take a few minutes)...'));
+    const result = spawnSync('cargo', ['install', '--git', 'https://github.com/rtk-ai/rtk', '--branch', 'master', 'rtk'], {
+        encoding: 'utf8',
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `failed to install rtk; run: ${RTK_INSTALL_COMMAND}` };
+    }
+    return { ok: true, message: 'installed rtk' };
+}
+
+function indexRepository() {
+    if (!commandExists(CODEBASE_MEMORY_BINARY)) {
+        return { ok: false, message: `${CODEBASE_MEMORY_BINARY} is not installed; skipped indexing` };
+    }
+    console.log(pc.dim(`  Running ${CODEBASE_MEMORY_BINARY} cli index_repository --repo-path . (first index of a large repo can take a while)...`));
+    const result = spawnSync(CODEBASE_MEMORY_BINARY, ['cli', 'index_repository', '--repo-path', '.'], {
+        cwd: targetDir,
+        encoding: 'utf8',
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `indexing failed; run manually: ${CODEBASE_MEMORY_BINARY} cli index_repository --repo-path .` };
+    }
+    return { ok: true, message: 'indexed repository with codebase-memory-mcp' };
+}
+
+function readJsonFile(filePath) {
+    if (!fs.existsSync(filePath)) return {};
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function writeJsonFile(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function mergeMcpJson(filePath, withType = false) {
+    const data = readJsonFile(filePath);
+    if (data === null) {
+        return { ok: false, message: `${filePath} is not valid JSON; skipped` };
+    }
+    data.mcpServers = data.mcpServers || {};
     const baseServers = {
         'codebase-memory-mcp': { command: CODEBASE_MEMORY_BINARY, args: [] },
         playwright: { command: 'playwright-mcp' },
         context7: { command: 'context7-mcp' }
-    };
-    if (data.permissions && Array.isArray(data.permissions.allow)) {
-        const requiredPermissions = [
-            "mcp__context7__resolve-library-id",
-            "mcp__context7__query-docs"
-        ];
-        for (const perm of requiredPermissions) {
-            if (!data.permissions.allow.includes(perm)) {
-                data.permissions.allow.push(perm);
-            }
-        }
-    }
-    for (const [name, server] of Object.entries(baseServers)) {
-        if (!data.mcpServers[name]) {
-            data.mcpServers[name] = withType ? { type: 'stdio', ...server } : server;
-        }
-    }
-    writeJsonFile(filePath, data);
-    const tools = Object.keys(baseServers).join(', ');
-    return { ok: true, message: `configured ${tools} MCP in ${filePath}` };
-}
-
-function appendMcpTomlIfMissing(filePath) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
-    const blocks = [];
-    if (!/\[mcp_servers\.context7\]/.test(existing)) {
-        blocks.push(`[mcp_servers.context7]
-command = "context7-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
+    };
+    if (data.permissions && Array.isArray(data.permissions.allow)) {
+        const requiredPermissions = [
+            "mcp__context7__resolve-library-id",
+            "mcp__context7__query-docs"
+        ];
+        for (const perm of requiredPermissions) {
+            if (!data.permissions.allow.includes(perm)) {
+                data.permissions.allow.push(perm);
+            }
+        }
+    }
+    for (const [name, server] of Object.entries(baseServers)) {
+        if (!data.mcpServers[name]) {
+            data.mcpServers[name] = withType ? { type: 'stdio', ...server } : server;
+        }
+    }
+    writeJsonFile(filePath, data);
+    const tools = Object.keys(baseServers).join(', ');
+    return { ok: true, message: `configured ${tools} MCP in ${filePath}` };
+}
+
+function appendMcpTomlIfMissing(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const blocks = [];
+    if (!/\[mcp_servers\.context7\]/.test(existing)) {
+        blocks.push(`[mcp_servers.context7]
+command = "context7-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+`);
+    }
     if (!/\[mcp_servers\.codebase-memory-mcp\]/.test(existing)) {
         blocks.push(`[mcp_servers.codebase-memory-mcp]
 command = "${CODEBASE_MEMORY_BINARY}"
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 `);
-    }
-    if (!/\[mcp_servers\.playwright\]/.test(existing)) {
-        blocks.push(`[mcp_servers.playwright]
-command = "playwright-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (blocks.length === 0) {        return { ok: true, message: `already configured ${filePath}` };
-    }
-    const separator = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
-    fs.writeFileSync(filePath, existing + separator + blocks.join('\n'), 'utf8');
+    }
+    if (!/\[mcp_servers\.playwright\]/.test(existing)) {
+        blocks.push(`[mcp_servers.playwright]
+command = "playwright-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+`);
+    }
+    if (blocks.length === 0) {        return { ok: true, message: `already configured ${filePath}` };
+    }
+    const separator = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
+    fs.writeFileSync(filePath, existing + separator + blocks.join('\n'), 'utf8');
     return { ok: true, message: `configured codebase-memory-mcp, context7, playwright MCP in ${filePath}` };
-}
-
+}
+
 const DOD_HOOK_MARKER = 'feature/refactor Definition-of-Done gate';
 
 function generateDodStopHookPrompt() {
-    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER} (defined in AGENTS.md "Gated Flow" and .agent/docs/workflow.md "Definition of Done"). Use the \`last_assistant_message\` field as the authoritative final response. Use \`transcript_path\` only for additional context because the transcript may not contain the final response yet.\n\nFor a feature or refactor (multi-file change, new behavior, or non-trivial refactor), the work must go through spec -> plan -> implement -> review before being reported as complete:\n- spec: \`.agent/workflows/spec.md\` (skip allowed for trivial/self-contained changes)\n- plan: \`.agent/workflows/plan.md\`, with a plan artifact such as \`docs/PLAN-*.md\` and explicit user approval\n- review: \`.agent/workflows/review.md\` five-axis review, with blocking issues resolved\n\nSimple/self-contained fixes (single-line, typo, or unambiguous one-file change) may use /simple and are explicitly exempt from spec+plan+review only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope. They should never be blocked when those criteria are met. Verification is still mandatory.\n\nSteps:\n1. If the input JSON has \`stop_hook_active: true\`, allow stopping immediately (already checked once this cycle; never block twice in a row).\n2. Inspect the changed files and the \`last_assistant_message\` field.\n3. If no source files changed, the final response does not claim the task is done/complete, or the final response explicitly contains FAST_PATH: simple-fix and the changed scope is clearly a simple/self-contained fix, allow stopping.\n4. If it is a feature/refactor-scale change and the final response claims completion, verify that a plan artifact exists with evidence of user approval and that a review pass was completed. If either gate is missing, block; a generic statement that the task was simple is not enough.\n5. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing and instruct the assistant to run the relevant workflow or explicitly state why the task qualifies as a simple fix.`;
+    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER}. This kit does not define its own workflow steps; it only verifies that evidence of the gate exists, regardless of which skill produced it (a Superpowers skill such as \`writing-plans\`/\`requesting-code-review\`, or an equivalent documented step). Use the \`last_assistant_message\` field as the authoritative final response. Use \`transcript_path\` only for additional context because the transcript may not contain the final response yet.\n\nFor a feature or refactor (multi-file change, new behavior, or non-trivial refactor), completion requires evidence of:\n- Plan: a plan was written and explicitly approved by the human before implementation started.\n- Review: the change was reviewed (correctness, simplicity, architecture, security, performance) and blocking issues were resolved.\n- Verification: tests or equivalent verification ran and passed.\n\nA one-file, unambiguous fix with no behavior/contract change is exempt from the Plan and Review evidence only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope. Verification is still mandatory in that case.\n\nSteps:\n1. If the input JSON has \`stop_hook_active: true\`, allow stopping immediately (already checked once this cycle; never block twice in a row).\n2. Inspect the changed files and the \`last_assistant_message\` field.\n3. If no source files changed, the final response does not claim the task is done/complete, or the final response explicitly contains FAST_PATH: simple-fix and the changed scope is clearly a simple/self-contained fix, allow stopping.\n4. If it is a feature/refactor-scale change and the final response claims completion, verify that the response (or the visible transcript) shows evidence of an approved plan and a completed review. If either is missing, block; a generic statement that the task was simple is not enough.\n5. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing without prescribing which skill or workflow must produce it.`;
 }
 
 function isDefinitionOfDoneHook(hook) {
     const prompt = hook && typeof hook.prompt === 'string' ? hook.prompt : '';
-    return prompt.includes(DOD_HOOK_MARKER) || (
-        prompt.includes('Input JSON (Stop hook payload)') &&
-        prompt.includes('.agent/workflows/spec.md') &&
-        prompt.includes('.agent/workflows/review.md')
-    );
+    return prompt.includes(DOD_HOOK_MARKER);
 }
 
 function mergeClaudeProjectHooks(filePath) {
@@ -2032,42 +1464,42 @@ function setupMcpServers(options = {}) {
     results.push(ensureCodebaseMemoryCli(install));
     results.push(ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp', install));
     results.push(ensureGlobalNpmPackage('playwright-mcp', '@playwright/mcp', install));
-
-    const codexConfig = homePath('.codex', 'config.toml');
-    if (codexConfig) results.push(appendMcpTomlIfMissing(codexConfig));
-
-    const geminiConfig = homePath('.gemini', 'config', 'mcp_config.json');
-    if (geminiConfig) results.push(mergeMcpJson(geminiConfig, false));
-
-    const antigravityIdeConfig = homePath('.gemini', 'antigravity-ide', 'mcp_config.json');
-    if (antigravityIdeConfig) results.push(mergeMcpJson(antigravityIdeConfig, false));
-
-    const antigravityConfig = homePath('.gemini', 'antigravity', 'mcp_config.json');
-    if (antigravityConfig && fs.existsSync(path.dirname(antigravityConfig))) {
-        results.push(mergeMcpJson(antigravityConfig, false));
-    }
-
-    const claudeConfig = homePath('.claude.json');
-    if (claudeConfig) results.push(mergeMcpJson(claudeConfig, true));
-
-    const claudeSettings = homePath('.claude', 'settings.json');
-    if (claudeSettings) results.push(mergeMcpJson(claudeSettings, true));
-
-    return results;
-}
-
-// --- 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;
-    }
-
+
+    const codexConfig = homePath('.codex', 'config.toml');
+    if (codexConfig) results.push(appendMcpTomlIfMissing(codexConfig));
+
+    const geminiConfig = homePath('.gemini', 'config', 'mcp_config.json');
+    if (geminiConfig) results.push(mergeMcpJson(geminiConfig, false));
+
+    const antigravityIdeConfig = homePath('.gemini', 'antigravity-ide', 'mcp_config.json');
+    if (antigravityIdeConfig) results.push(mergeMcpJson(antigravityIdeConfig, false));
+
+    const antigravityConfig = homePath('.gemini', 'antigravity', 'mcp_config.json');
+    if (antigravityConfig && fs.existsSync(path.dirname(antigravityConfig))) {
+        results.push(mergeMcpJson(antigravityConfig, false));
+    }
+
+    const claudeConfig = homePath('.claude.json');
+    if (claudeConfig) results.push(mergeMcpJson(claudeConfig, true));
+
+    const claudeSettings = homePath('.claude', 'settings.json');
+    if (claudeSettings) results.push(mergeMcpJson(claudeSettings, true));
+
+    return results;
+}
+
+// --- 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;
@@ -2078,140 +1510,142 @@ async function main() {
         return;
     }
 
+    if (command === 'prompt') {
+        printProjectPrompt();
+        return;
+    }
+
     if (command === 'setup') {
         await runSetup(rawArgs.slice(1));
         return;
     }
 
     if (command !== 'init') {
-        console.error(pc.red(`Unknown command: ${command}`));
-        printHelp();
-        process.exit(1);
-    }
-
-    const assumeYes = args.includes('--yes') || args.includes('-y');
-    const skipMcpSetup = args.includes('--no-setup-mcp') || process.env.THACHVD_KIT_SKIP_MCP_SETUP === '1';
-
-    console.log(pc.bold(pc.cyan('='.repeat(50))));
-    console.log('  ' + pc.bold('thachvd-kit') + ' - AI Project Bootstrap');
-    console.log('  Generates shared agent rules and configures MCP tooling');
-    console.log(pc.bold(pc.cyan('='.repeat(50))));
-
-    console.log(pc.dim('  Scanning current project files for a baseline...\n'));
-    const scanned = scanProject();
-
-    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('');
-    }
-
-    // Combine data
-    const data = {
-        project_name: scanned?.project_name || path.basename(targetDir),
-        description: scanned?.description || 'A software project',
-        project_type: scanned?.project_type || 'web-app',
-        primary_language: scanned?.primary_language || 'typescript',
-        frameworks: scanned?.frameworks || [],
-        database: scanned?.database || 'none',
-        uses_docker: scanned?.uses_docker ?? true,
-        cloud: scanned?.cloud || 'none',
-        package_manager: scanned?.package_manager || 'auto-detect',
-        test_framework: scanned?.test_framework || 'auto-detect',
-        max_file_lines: scanned?.max_file_lines || '300'
-    };
-
-    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.error(pc.red(`Unknown command: ${command}`));
+        printHelp();
+        process.exit(1);
+    }
+
+    const assumeYes = args.includes('--yes') || args.includes('-y');
+    const skipMcpSetup = args.includes('--no-setup-mcp') || process.env.THACHVD_KIT_SKIP_MCP_SETUP === '1';
+
+    console.log(pc.bold(pc.cyan('='.repeat(50))));
+    console.log('  ' + pc.bold('thachvd-kit') + ' - AI Project Bootstrap');
+    console.log('  Generates shared agent rules and configures MCP tooling');
+    console.log(pc.bold(pc.cyan('='.repeat(50))));
+
+    console.log(pc.dim('  Scanning current project files for a baseline...\n'));
+    const scanned = scanProject();
+
+    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('');
+    }
+
+    // Combine data
+    const data = {
+        project_name: scanned?.project_name || path.basename(targetDir),
+        description: scanned?.description || 'A software project',
+        project_type: scanned?.project_type || 'web-app',
+        primary_language: scanned?.primary_language || 'typescript',
+        frameworks: scanned?.frameworks || [],
+        database: scanned?.database || 'none',
+        uses_docker: scanned?.uses_docker ?? true,
+        cloud: scanned?.cloud || 'none',
+        package_manager: scanned?.package_manager || 'auto-detect',
+        test_framework: scanned?.test_framework || 'auto-detect',
+        max_file_lines: scanned?.max_file_lines || '300'
+    };
+
+    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);
+
     const shouldSetupMcp = args.includes('--setup-mcp') && !skipMcpSetup;
-
-    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
-
-    // Shared entry files are written after the .agent folder is available.
-
+
+    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
+
+    // Shared entry files are written after the .agent folder is available.
+
     console.log(`  ${pc.green('OK')} Project context generation enabled; workflow skills remain client-managed by Superpowers`);
-
-
-    const generatedFiles = [
-        ['AGENTS.md', generateSharedAgentsMd(data)],
-        ['CLAUDE.md', generateSharedClaudeMd()],
-        ['GEMINI.md', generateSharedGeminiMd()],
-        ['.cursorrules', generateSharedCursorrules(data)],
-        [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()],
+
+
+    const generatedFiles = [
+        ['AGENTS.md', generateSharedAgentsMd(data)],
+        ['CLAUDE.md', generateSharedClaudeMd()],
+        ['GEMINI.md', generateSharedGeminiMd()],
+        ['.cursorrules', generateSharedCursorrules(data)],
+        [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()],
         [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)],
-        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()]
-    ];
-
-    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)}`);
-    }
-
+        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()],
+        [path.join('.agent', 'docs', 'index-project-prompt.md'), generateIndexProjectPrompt()]
+    ];
+
+    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)}`);
+    }
+
     if (shouldSetupMcp) {
-        console.log(`\n${pc.bold(pc.cyan('Configuring MCP'))}`);
-        for (const result of setupMcpServers()) {
-            const marker = result.ok ? pc.green('OK') : pc.yellow('~');
-            console.log(`  ${marker} ${result.message}`);
-        }
-    }
-
-    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, Claude Code, and Cursor
-    - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
-    - ${pc.bold('GEMINI.md')} Antigravity entry
-    - ${pc.bold('.cursorrules')} Cursor entry
-    - ${pc.bold('.agent/docs/')} scan-based project rules, including ${pc.bold('getting-started.md')} (standard flow vs fast path)
-    - ${pc.bold('.agent/docs/')} project context and local operating notes
-
-  ${pc.bold('MCP/tooling setup:')}
+        console.log(`\n${pc.bold(pc.cyan('Configuring MCP'))}`);
+        for (const result of setupMcpServers()) {
+            const marker = result.ok ? pc.green('OK') : pc.yellow('~');
+            console.log(`  ${marker} ${result.message}`);
+        }
+    }
+
+    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, Claude Code, and Cursor
+    - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
+    - ${pc.bold('GEMINI.md')} Antigravity entry
+    - ${pc.bold('.cursorrules')} Cursor entry
+    - ${pc.bold('.agent/docs/')} scan-based project rules and local operating notes
+    - ${pc.bold('.agent/docs/index-project-prompt.md')} durable onboarding prompt
+
+  ${pc.bold('MCP/tooling setup:')}
     - Superpowers is the workflow backend; install it from the official client/plugin surface
-    - Run ${pc.bold('thachvd-kit setup')} to configure codebase-memory MCP and optional RTK
-
-  ${pc.bold('Next steps:')}
-    1. Read ${pc.bold('.agent/docs/getting-started.md')} for the standard Superpowers flow
-    2. Run ${pc.bold('thachvd-kit setup')} for optional integrations
+    - Run ${pc.bold('thachvd-kit setup')} to configure codebase-memory MCP and recommended RTK
+
+  ${pc.bold('Next steps:')}
+    1. Run ${pc.bold('thachvd-kit prompt')} and paste the saved prompt into your AI editor
+    2. Install Superpowers and RTK, then run ${pc.bold('thachvd-kit setup')}
     3. Run ${pc.bold('thachvd-kit doctor')} to verify the machine
-    4. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, and ${pc.bold('.agent/docs/')}
-
-  ${pc.bold('Copy this prompt into your AI editor:')}
-${pc.dim('---')}
-Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
-Use Superpowers for the workflow and use codebase-memory MCP for structural code discovery when available.
-Ask me what this project does and any important conventions I want preserved.
-Then scan this repository and refine the generated context docs with factual rules.
-Do not implement product code during onboarding.
+    4. Re-run ${pc.bold('thachvd-kit prompt')} whenever you need the onboarding prompt again
+
+  ${pc.bold('Onboarding prompt saved to .agent/docs/index-project-prompt.md:')}
+${pc.dim('---')}
+${generateIndexProjectPrompt().trim()}
 ${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);
+});
+