thachvd-kit 1.0.7 → 1.0.10

package/README.md

@@ -1,82 +1,111 @@
-# thachvd-kit — Universal Agent Kit
-
-A universally compatible, high-power agent toolkit designed for **Antigravity**, **Claude Code**, and **Codex/OpenCode**. 
-It dynamically sets up rules and intelligently routes agent skills based on your project's technology stack using a CLI wizard.
-
-## 🚀 Quick Start
-
-You can initialize `thachvd-kit` in **any** project directory without manually copying files!
-
-Simply run the wizard:
+# thachvd-kit
+
+`thachvd-kit` bootstraps project context for AI coding agents such as Antigravity, Claude Code, and Codex.
+
+It installs a local `.agent/` kit, generates `PROJECT_CONTEXT.md`, and can scan an existing codebase to infer stack, framework, database, and infra signals before your agent starts working.
+
+## Quick Start
+
+Install globally:
 
 ```bash
-npx thachvd-kit init
-# or
-npx github:thachvd/thachvd-kit init
+npm install -g thachvd-kit
 ```
 
-The interactive wizard will first ask whether this is a new project or an existing one.
-If it is an existing project, it can scan the current codebase to prefill `PROJECT_CONTEXT.md`, or let you enter everything manually.
-The scan mode uses evidence-based detectors and shows why a framework was inferred, so you can quickly confirm or correct it.
-After init, you can also generate an AI refinement prompt to let your editor/agent deepen the project context.
+Then run inside any project folder:
 
 ```bash
-thachvd-kit init --scan
+thachvd-kit init
 ```
 
-Use `--scan` when you want to skip straight to codebase detection for an existing project.
-
-The wizard will then ask you a few questions about your project (frontend, backend, database, infrastructure, etc.). 
-Based on your answers, it will:
-1. **Copy** the highly optimized agents, skills, and rules to a `.agent` folder inside your project.
-2. **Generate** a smart `PROJECT_CONTEXT.md` file tailored specifically to your chosen stack.
-3. **Generate** a `CLAUDE.md` to ensure maximum cross-platform compatibility.
-
-### Global Installation (Like `agkit-init`)
-
-If you want to install it globally on your machine:
-
-```bash
-npm install -g github:thachvd/thachvd-kit
-```
-
-Then, whenever you start a new project, just type:
+You can also skip directly to scan mode:
 
 ```bash
-thachvd-kit init
+thachvd-kit init --scan
 ```
-
----
-
-## 🧠 How It Works
-
-This kit uses a **Universal Protocol Engine** (`GEMINI.md` / `CLAUDE.md`) that is completely stack-agnostic. 
-
-Instead of hardcoding rules, it relies on the `PROJECT_CONTEXT.md` file (generated by the CLI wizard) to automatically detect the environment and load the **right** skills:
-
-- Are you using **Laravel**? It loads `laravel-patterns`, `laravel-security`, and `laravel-tdd`.
-- Are you using **Go**? It brings in `golang-patterns` and `golang-testing`.
-- Are you using **React**? It primes the agent with `react-frontend` and `frontend-design`.
-- Are you using **Next.js**? It primes the agent with `nextjs-react-expert` and `frontend-design`.
-- Are you using **Tauri**? It primes the agent with `rust-pro` and `desktop-design`.
-
-## 🛠️ Features
-
-- 🎯 **50+ Production-Grade Skills:** From architecture patterns to multi-agent parallel dispatching.
-- ⚡️ **Subagent-Driven Development:** Agents act as your implementer, spec-verifier, and code-reviewer without human bottlenecks.
-- 🛡️ **Zero Hallucination Completion:** Built-in `verification-before-completion` forces the agent to run tests before claiming "done".
-- 🚀 **Isolated Worktrees:** Automatically manages hidden `git worktrees` so you never pollute your main branch with broken iterations.
-
-## Directory Structure (Inside your `.agent` folder)
-
-```text
-.agent/
-├── rules/GEMINI.md      ← The Universal Rules Engine
-├── agents/              ← 20+ specialized agents (frontend, backend, db, ...)
-├── skills/              ← 50+ domain & workflow skills
-└── workflows/           ← Executable workflows
-```
-
----
-
-**Made with ❤️ for AI-native software engineering.**
+
+## What `init` Does
+
+`thachvd-kit init` now supports both new and existing projects:
+
+- New project: enter context manually.
+- Existing project: choose scan mode or manual mode.
+- Scan mode: detect stack from the codebase, show evidence, then either accept detected values or review/edit them.
+
+Generated files:
+
+- `.agent/agents`
+- `.agent/rules`
+- `.agent/skills`
+- `.agent/workflows`
+- `PROJECT_CONTEXT.md`
+- `CLAUDE.md`
+- `AI_CONTEXT_REFINEMENT.md` when first-session AI refinement is enabled
+
+## Scan Behavior
+
+The scanner is hybrid and practical:
+
+- App stack detection uses an inferred `app_root` so nested apps like `src/` can still resolve Laravel, CakePHP, Next.js, and similar stacks correctly.
+- Infra detection stays repo-wide, so folders like `dev/`, `stg/`, `prod/` can still contribute Docker and CI evidence.
+- Noise folders such as `vendor`, `node_modules`, `.git`, `dist`, and `build` are ignored during recursive scan.
+
+The scan preview surfaces:
+
+- app root
+- project type
+- primary language
+- frameworks
+- database
+- package manager
+- test framework
+- cloud
+- infrastructure
+- CI/CD
+- evidence for each inferred framework
+
+## AI Refinement Flow
+
+`init` creates a baseline `PROJECT_CONTEXT.md`.
+
+If you enable first-session AI refinement, the generated context is marked with:
+
+- `context.status: baseline`
+- `context.needs_ai_refinement: true`
+
+Then, when your agent opens the project, `GEMINI.md` / `CLAUDE.md` instruct it to:
+
+1. Read `PROJECT_CONTEXT.md`
+2. Refine the context once if `needs_ai_refinement` is `true`
+3. Update the file to `context.status: refined`
+4. Set `context.needs_ai_refinement: false`
+
+This keeps `init` simple while still allowing a deeper AI pass without requiring API-key integration inside the CLI.
+
+## Skill Resolution
+
+The kit auto-loads generic and framework-specific skills based on detected context.
+
+Examples:
+
+- React -> `react-frontend`, `frontend-design`
+- Next.js -> `nextjs-react-expert`, `frontend-design`
+- Laravel -> `laravel-patterns`, `laravel-security`, `laravel-tdd`
+- Tauri -> `rust-pro`, `desktop-design`
+
+Generic quality skills such as `clean-code` and `systematic-debugging` are always included.
+
+## Directory Layout
+
+```text
+.agent/
+├── agents/
+├── rules/
+├── skills/
+└── workflows/
+```
+
+## Notes
+
+- `thachvd-kit` is compatible with Codex workflows through `PROJECT_CONTEXT.md` and `CLAUDE.md`; it does not directly control Codex sessions.
+- The npm package page updates only after a new `npm publish`, not just after pushing to GitHub.

package/bin/cli.js

@@ -107,6 +107,7 @@ 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(`
@@ -126,6 +127,21 @@ ${pc.bold('Options:')}
 `);
 }
 
+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: () => {
@@ -139,6 +155,10 @@ 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;
@@ -149,6 +169,16 @@ function readJsonIfExists(...parts) {
     }
 }
 
+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 '';
@@ -159,17 +189,27 @@ function readTextIfExists(...parts) {
     }
 }
 
-function detectPackageManager() {
-    if (fileExists('pnpm-lock.yaml')) return 'pnpm';
-    if (fileExists('yarn.lock')) return 'yarn';
-    if (fileExists('bun.lockb') || fileExists('bun.lock')) return 'bun';
-    if (fileExists('package-lock.json')) return 'npm';
-    if (fileExists('uv.lock')) return 'uv';
-    if (fileExists('poetry.lock')) return 'pip';
-    if (fileExists('requirements.txt') || fileExists('pyproject.toml')) return 'pip';
-    if (fileExists('go.mod')) return 'go mod';
-    if (fileExists('Cargo.toml')) return 'cargo';
-    if (fileExists('composer.json')) return 'composer';
+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';
 }
 
@@ -177,6 +217,76 @@ 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;
 }
@@ -365,10 +475,11 @@ const FRAMEWORK_DETECTORS = [
         id: 'django',
         kind: 'backend',
         language: 'python',
-        projectType: 'api',
+        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('manage.py'), 'found manage.py', 2),
+            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
         ])
     },
     {
@@ -384,17 +495,18 @@ const FRAMEWORK_DETECTORS = [
         id: 'laravel',
         kind: 'backend',
         language: 'php',
-        projectType: 'api',
+        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('artisan'), 'found artisan', 3),
+            evidenceIf(ctx.fileExists('resources', 'views'), 'found resources/views', 1)
         ])
     },
     {
         id: 'cakephp',
         kind: 'backend',
         language: 'php',
-        projectType: 'api',
+        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),
@@ -403,18 +515,21 @@ const FRAMEWORK_DETECTORS = [
             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('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: 'api',
+        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('config', 'bundles.php'), 'found config/bundles.php', 1),
+            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
         ])
     },
     {
@@ -459,10 +574,11 @@ const FRAMEWORK_DETECTORS = [
         id: 'rails',
         kind: 'backend',
         language: 'ruby',
-        projectType: 'api',
+        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('bin', 'rails'), 'found bin/rails', 2),
+            evidenceIf(ctx.fileExists('app', 'views'), 'found app/views', 1)
         ])
     },
     {
@@ -532,9 +648,10 @@ const FRAMEWORK_DETECTORS = [
 ];
 
 function scanProject() {
-    const pkg = readJsonIfExists('package.json') || {};
-    const composer = readJsonIfExists('composer.json') || {};
-    const rootEntries = fs.existsSync(targetDir) ? fs.readdirSync(targetDir) : [];
+    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 || {}),
@@ -553,17 +670,20 @@ function scanProject() {
         depNames,
         composerDepNames,
         rootEntries,
-        fileExists,
-        requirementsText: readTextIfExists('requirements.txt'),
-        pyprojectText: readTextIfExists('pyproject.toml'),
-        goModText: readTextIfExists('go.mod'),
-        pubspecText: readTextIfExists('pubspec.yaml'),
-        gemfileText: readTextIfExists('Gemfile'),
-        pomText: readTextIfExists('pom.xml'),
-        gradleText: `${readTextIfExists('build.gradle')}\n${readTextIfExists('build.gradle.kts')}`,
-        cargoText: `${readTextIfExists('Cargo.toml')}\n${readTextIfExists('src-tauri', 'Cargo.toml')}`,
-        csprojText: rootCsproj ? readTextIfExists(rootCsproj) : '',
-        programCsText: readTextIfExists('Program.cs')
+        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
@@ -605,9 +725,10 @@ function scanProject() {
     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 (fileExists('package.json') && pkg.bin) projectType = 'cli';
+    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';
@@ -622,28 +743,30 @@ function scanProject() {
     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 (fileExists('go.mod')) testFramework = 'go test';
+    else if (fileExistsAt(appRoot, 'go.mod')) testFramework = 'go test';
     else if (textMatches(ctx.gemfileText, /^\s*gem\s+["']rspec["']/im)) testFramework = 'rspec';
 
-    if (fileExists('Dockerfile') || fileExists('docker-compose.yml') || fileExists('docker-compose.yaml')) {
+    if (repoHasAny(targetDir, [['Dockerfile'], ['docker-compose.yml'], ['docker-compose.yaml']])) {
         infrastructure.push('docker');
     }
 
-    if (fileExists('vercel.json')) {
+    if (repoHasAny(targetDir, [['vercel.json']])) {
         cloud = 'vercel';
         infrastructure.push('vercel');
-    } else if (fileExists('fly.toml')) {
+    } else if (repoHasAny(targetDir, [['fly.toml']])) {
         cloud = 'fly';
         infrastructure.push('fly');
-    } else if (fileExists('railway.json') || fileExists('railway.toml')) {
+    } else if (repoHasAny(targetDir, [['railway.json'], ['railway.toml']])) {
         cloud = 'railway';
         infrastructure.push('railway');
     }
 
-    if (fileExists('.github', 'workflows')) ciCd = 'github-actions';
-    else if (fileExists('.gitlab-ci.yml')) ciCd = 'gitlab-ci';
-    else if (fileExists('.circleci', 'config.yml')) ciCd = 'circleci';
-    else if (fileExists('Jenkinsfile')) ciCd = 'jenkins';
+    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('; ')}`] : []),
@@ -652,6 +775,7 @@ function scanProject() {
 
     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',
@@ -659,7 +783,7 @@ function scanProject() {
         framework_details: frameworkDetails,
         scan_evidence: scanEvidence,
         database: DATABASE_CHOICES.includes(database) ? database : 'none',
-        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager()) ? detectPackageManager() : 'auto-detect',
+        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager(appRoot)) ? detectPackageManager(appRoot) : 'auto-detect',
         uses_docker: infrastructure.includes('docker'),
         cloud,
         infrastructure: uniq(infrastructure),
@@ -745,21 +869,33 @@ ${(data.scan_evidence || []).map(line => '- ' + line).join('\n')}
 # Generated by thachvd-kit init wizard on ${new Date().toISOString().split('T')[0]}
 # Edit freely — this is your project's brain.
 
-## Project
-
-- **Name:** ${data.project_name}
-- **Description:** ${data.description}
-- **Type:** ${data.project_type}
-
----
+## Project
+
+- **Name:** ${data.project_name}
+- **Description:** ${data.description}
+- **Type:** ${data.project_type}
+
+---
+
+## Context Status
+
+\`\`\`yaml
+context:
+  status: ${data.context_status || 'baseline'}
+  needs_ai_refinement: ${data.needs_ai_refinement ? 'true' : 'false'}
+  last_refined_at: ${data.last_refined_at || 'not-yet-refined'}
+\`\`\`
+
+---
 
 ## Stack
 
 \`\`\`yaml
-stack:
-  primary_language: ${data.primary_language}
-  frameworks: [${(data.frameworks || []).join(', ')}]
-  database: ${data.database || 'none'}
+stack:
+  app_root: ${data.app_root || '.'}
+  primary_language: ${data.primary_language}
+  frameworks: [${(data.frameworks || []).join(', ')}]
+  database: ${data.database || 'none'}
   infrastructure: [${(data.infrastructure || []).join(', ')}]
   package_manager: ${data.package_manager || 'auto-detect'}
   test_framework: ${data.test_framework || 'auto-detect'}
@@ -992,8 +1128,11 @@ async function main() {
     let requestAiRefinement = false;
 
     if (useScan) {
-        console.log(`${pc.bold('  Scan result:')} ${scanned.primary_language} | ${scanned.frameworks.join(', ') || 'no framework'}`);
-        console.log(`  ${pc.bold('Detected infra:')} ${scanned.infrastructure.join(', ') || 'none'}\n`);
+        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}`));
@@ -1083,6 +1222,21 @@ async function main() {
     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 || '.';
+
+    if (!assumeYes) {
+        const aiRefineAnswer = await askQuestions({
+            type: 'confirm',
+            name: 'ai_refine',
+            message: 'Should the agent refine PROJECT_CONTEXT.md on first session start?',
+            initial: useScan
+        });
+        requestAiRefinement = Boolean(aiRefineAnswer.ai_refine);
+    }
+
+    data.context_status = 'baseline';
+    data.needs_ai_refinement = requestAiRefinement;
+    data.last_refined_at = 'not-yet-refined';
     data.infrastructure = [];
     if (data.uses_docker) data.infrastructure.push('docker');
     if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
@@ -1118,16 +1272,6 @@ async function main() {
     fs.writeFileSync(claudeMdPath, generateClaudeMd(data), 'utf8');
     console.log(`  ${pc.green('✓')} Generated ${pc.bold('CLAUDE.md')}`);
 
-    if (!assumeYes) {
-        const aiRefineAnswer = await askQuestions({
-            type: 'confirm',
-            name: 'ai_refine',
-            message: 'Do you want an AI refinement prompt for PROJECT_CONTEXT.md?',
-            initial: useScan
-        });
-        requestAiRefinement = Boolean(aiRefineAnswer.ai_refine);
-    }
-
     let aiRefinementPath = null;
     if (requestAiRefinement) {
         aiRefinementPath = path.join(targetDir, 'AI_CONTEXT_REFINEMENT.md');

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.7",
-    "description": "Universal Agent Kit for Antigravity, Claude Code, and OpenCode",
+    "version": "1.0.10",
+    "description": "Project context bootstrap kit for Antigravity, Claude Code, and Codex",
     "bin": {
         "thachvd-kit": "./bin/cli.js"
     },
@@ -38,7 +38,7 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "git@github_home:holdon1996/thachvd-kit.git"
+        "url": "https://github.com/holdon1996/thachvd-kit.git"
     },
     "homepage": "https://github.com/holdon1996/thachvd-kit",
     "bugs": {

package/rules/GEMINI.md

@@ -10,16 +10,19 @@ trigger: always_on
 
 ## MANDATORY FIRST ACTION
 
-**At session start — before anything else:**
-
-```
-1. Read PROJECT_CONTEXT.md (if exists) → load stack, agents, constraints
-2. If missing → run @[skills/project-onboarding] to create it
-3. Confirm: "Context loaded: [Project Name] | Stack: [Stack] | Ready."
-```
-
-> All routing decisions below depend on PROJECT_CONTEXT.md.
-> Without it, ask user to run: `python scripts/init.py`
+**At session start — before anything else:**
+
+```
+1. Read PROJECT_CONTEXT.md (if exists) → load stack, agents, constraints
+2. If missing → run @[skills/project-onboarding] to create it
+3. Read PROJECT_CONTEXT context.status and context.needs_ai_refinement
+4. If needs_ai_refinement = true → scan project with AI, update PROJECT_CONTEXT.md, set status=refined and needs_ai_refinement=false
+5. Confirm: "Context loaded: [Project Name] | Stack: [Stack] | Ready."
+```
+
+> All routing decisions below depend on PROJECT_CONTEXT.md.
+> Without it, ask user to run: `python scripts/init.py`
+> Baseline context must be refined once when `context.needs_ai_refinement = true`.
 
 ---
 

package/scripts/init.py

@@ -156,6 +156,7 @@ CLOUDS_ALL = ["aws", "gcp", "azure", "vercel", "fly", "railway", "digitalocean",
 FRONTEND_FRAMEWORKS = ["vue", "react", "next", "nuxt", "svelte", "angular"]
 BACKEND_FRAMEWORKS = ["laravel", "cakephp", "symfony", "codeigniter", "express", "fastapi", "django", "flask", "gin", "fiber", "echo", "nestjs", "rails", "spring", "aspnet", "axum", "actix"]
 MOBILE_DESKTOP_FRAMEWORKS = ["tauri", "flutter", "react-native"]
+IGNORED_SCAN_DIRS = {".git", "node_modules", "vendor", "dist", "build", "coverage", ".next", ".nuxt", ".turbo", ".cache", "storage", "tmp"}
 
 def read_text_if_exists(*parts):
     path = Path.cwd().joinpath(*parts)
@@ -171,23 +172,26 @@ def read_json_if_exists(*parts):
     except Exception:
         return None
 
-def detect_package_manager():
-    cwd = Path.cwd()
-    if (cwd / "pnpm-lock.yaml").exists(): return "pnpm"
-    if (cwd / "yarn.lock").exists(): return "yarn"
-    if (cwd / "bun.lockb").exists() or (cwd / "bun.lock").exists(): return "bun"
-    if (cwd / "package-lock.json").exists(): return "npm"
-    if (cwd / "uv.lock").exists(): return "uv"
-    if (cwd / "poetry.lock").exists(): return "poetry"
-    if (cwd / "requirements.txt").exists() or (cwd / "pyproject.toml").exists(): return "pip"
-    if (cwd / "go.mod").exists(): return "go mod"
-    if (cwd / "Cargo.toml").exists(): return "cargo"
-    if (cwd / "composer.json").exists(): return "composer"
+def detect_package_manager(base_dir=None):
+    base_dir = base_dir or Path.cwd()
+    if path_exists(base_dir, "pnpm-lock.yaml"): return "pnpm"
+    if path_exists(base_dir, "yarn.lock"): return "yarn"
+    if path_exists(base_dir, "bun.lockb") or path_exists(base_dir, "bun.lock"): return "bun"
+    if path_exists(base_dir, "package-lock.json"): return "npm"
+    if path_exists(base_dir, "uv.lock"): return "uv"
+    if path_exists(base_dir, "poetry.lock"): return "poetry"
+    if path_exists(base_dir, "requirements.txt") or path_exists(base_dir, "pyproject.toml"): return "pip"
+    if path_exists(base_dir, "go.mod"): return "go mod"
+    if path_exists(base_dir, "Cargo.toml"): return "cargo"
+    if path_exists(base_dir, "composer.json"): return "composer"
     return "auto-detect"
 
 def uniq(values):
     return list(dict.fromkeys(v for v in values if v))
 
+def path_exists(base_dir, *parts):
+    return base_dir.joinpath(*parts).exists()
+
 def evidence_if(condition, label, weight=1):
     return {"label": label, "weight": weight} if condition else None
 
@@ -215,10 +219,73 @@ def has_composer_dependency(composer_dep_names, *names):
 def text_matches(text, pattern):
     return bool(text and re.search(pattern, text, re.IGNORECASE | re.MULTILINE))
 
+def detect_app_root(base_dir):
+    candidates = [base_dir]
+    queue = [(base_dir, 0)]
+    while queue:
+        current, depth = queue.pop(0)
+        if depth >= 2:
+            continue
+        try:
+            entries = list(current.iterdir())
+        except Exception:
+            continue
+        for entry in entries:
+            if not entry.is_dir():
+                continue
+            if entry.name in IGNORED_SCAN_DIRS:
+                continue
+            candidates.append(entry)
+            queue.append((entry, depth + 1))
+
+    def score_candidate(path):
+        score = 0
+        if path_exists(path, "composer.json"): score += 5
+        if path_exists(path, "package.json"): score += 4
+        if path_exists(path, "Cargo.toml"): score += 4
+        if path_exists(path, "go.mod"): score += 4
+        if path_exists(path, "pyproject.toml") or path_exists(path, "requirements.txt"): score += 4
+        if path_exists(path, "artisan"): score += 5
+        if path_exists(path, "bin", "cake") or path_exists(path, "app", "Config", "core.php"): score += 5
+        if path_exists(path, "src-tauri", "tauri.conf.json") or path_exists(path, "src-tauri", "tauri.conf.json5"): score += 5
+        if path_exists(path, "manage.py"): score += 4
+        if path_exists(path, "Gemfile"): score += 4
+        if path_exists(path, "pom.xml") or path_exists(path, "build.gradle") or path_exists(path, "build.gradle.kts"): score += 4
+        if path_exists(path, "app", "View") or path_exists(path, "resources", "views") or path_exists(path, "templates") or path_exists(path, "app", "views"): score += 2
+        return score
+
+    ranked = [{"path": path, "score": score_candidate(path)} for path in candidates]
+    ranked = [item for item in ranked if item["score"] > 0]
+    ranked.sort(key=lambda item: (-item["score"], len(str(item["path"]))))
+    return ranked[0]["path"] if ranked else base_dir
+
+def repo_has_any(base_dir, relative_paths, max_depth=3):
+    queue = [(base_dir, 0)]
+    while queue:
+        current, depth = queue.pop(0)
+        for rel_parts in relative_paths:
+            if path_exists(current, *rel_parts):
+                return True
+        if depth >= max_depth:
+            continue
+        try:
+            entries = list(current.iterdir())
+        except Exception:
+            continue
+        for entry in entries:
+            if not entry.is_dir():
+                continue
+            if entry.name in IGNORED_SCAN_DIRS:
+                continue
+            queue.append((entry, depth + 1))
+    return False
+
 def scan_project():
-    pkg = read_json_if_exists("package.json") or {}
-    composer = read_json_if_exists("composer.json") or {}
-    root_entries = [p.name for p in Path.cwd().iterdir()] if Path.cwd().exists() else []
+    repo_root = Path.cwd()
+    app_root = detect_app_root(repo_root)
+    pkg = read_json_if_exists(app_root, "package.json") or {}
+    composer = read_json_if_exists(app_root, "composer.json") or {}
+    root_entries = [p.name for p in app_root.iterdir()] if app_root.exists() else []
     root_csproj = next((name for name in root_entries if name.endswith(".csproj")), "")
     deps = {}
     for key in ("dependencies", "devDependencies", "peerDependencies"):
@@ -228,53 +295,53 @@ def scan_project():
     for key in ("require", "require-dev"):
         composer_deps.update(composer.get(key, {}) or {})
     composer_dep_names = set(composer_deps.keys())
-    requirements = read_text_if_exists("requirements.txt")
-    pyproject = read_text_if_exists("pyproject.toml")
-    go_mod = read_text_if_exists("go.mod")
-    pubspec = read_text_if_exists("pubspec.yaml")
-    gemfile = read_text_if_exists("Gemfile")
-    pom = read_text_if_exists("pom.xml")
-    gradle = f"{read_text_if_exists('build.gradle')}\n{read_text_if_exists('build.gradle.kts')}"
-    cargo = f"{read_text_if_exists('Cargo.toml')}\n{read_text_if_exists('src-tauri/Cargo.toml')}"
-    csproj = read_text_if_exists(root_csproj) if root_csproj else ""
-    program_cs = read_text_if_exists("Program.cs")
+    requirements = read_text_if_exists(app_root, "requirements.txt")
+    pyproject = read_text_if_exists(app_root, "pyproject.toml")
+    go_mod = read_text_if_exists(app_root, "go.mod")
+    pubspec = read_text_if_exists(app_root, "pubspec.yaml")
+    gemfile = read_text_if_exists(app_root, "Gemfile")
+    pom = read_text_if_exists(app_root, "pom.xml")
+    gradle = f"{read_text_if_exists(app_root, 'build.gradle')}\n{read_text_if_exists(app_root, 'build.gradle.kts')}"
+    cargo = f"{read_text_if_exists(app_root, 'Cargo.toml')}\n{read_text_if_exists(app_root, 'src-tauri/Cargo.toml')}"
+    csproj = read_text_if_exists(app_root, root_csproj) if root_csproj else ""
+    program_cs = read_text_if_exists(app_root, "Program.cs")
 
     language_detections = [
         build_detection("typescript", [
-            evidence_if(Path("tsconfig.json").exists(), "found tsconfig.json", 4),
+            evidence_if(path_exists(app_root, "tsconfig.json"), "found tsconfig.json", 4),
             evidence_if(has_dependency(dep_names, "typescript", "ts-node", "tsx"), "package.json -> typescript toolchain", 2),
         ]),
         build_detection("javascript", [
-            evidence_if(Path("package.json").exists(), "found package.json", 2),
+            evidence_if(path_exists(app_root, "package.json"), "found package.json", 2),
             evidence_if(bool(dep_names), "package.json -> JavaScript dependency graph", 1),
         ]),
         build_detection("python", [
-            evidence_if(Path("requirements.txt").exists(), "found requirements.txt", 3),
-            evidence_if(Path("pyproject.toml").exists(), "found pyproject.toml", 2),
+            evidence_if(path_exists(app_root, "requirements.txt"), "found requirements.txt", 3),
+            evidence_if(path_exists(app_root, "pyproject.toml"), "found pyproject.toml", 2),
             evidence_if(text_matches(pyproject, r"\[tool\.(poetry|uv|hatch|pdm)\]"), "pyproject.toml -> Python tool section", 2),
         ]),
         build_detection("go", [
-            evidence_if(Path("go.mod").exists(), "found go.mod", 4),
+            evidence_if(path_exists(app_root, "go.mod"), "found go.mod", 4),
         ]),
         build_detection("php", [
-            evidence_if(Path("composer.json").exists(), "found composer.json", 4),
+            evidence_if(path_exists(app_root, "composer.json"), "found composer.json", 4),
             evidence_if(bool(composer_dep_names), "composer.json -> PHP dependency graph", 1),
         ]),
         build_detection("rust", [
-            evidence_if(Path("Cargo.toml").exists(), "found Cargo.toml", 4),
-            evidence_if(Path("src-tauri/Cargo.toml").exists(), "found src-tauri/Cargo.toml", 5),
+            evidence_if(path_exists(app_root, "Cargo.toml"), "found Cargo.toml", 4),
+            evidence_if(path_exists(app_root, "src-tauri", "Cargo.toml"), "found src-tauri/Cargo.toml", 5),
         ]),
         build_detection("java", [
-            evidence_if(Path("pom.xml").exists(), "found pom.xml", 4),
-            evidence_if(Path("build.gradle").exists() or Path("build.gradle.kts").exists(), "found Gradle build file", 3),
+            evidence_if(path_exists(app_root, "pom.xml"), "found pom.xml", 4),
+            evidence_if(path_exists(app_root, "build.gradle") or path_exists(app_root, "build.gradle.kts"), "found Gradle build file", 3),
         ]),
         build_detection("ruby", [
-            evidence_if(Path("Gemfile").exists(), "found Gemfile", 4),
-            evidence_if(Path("config.ru").exists(), "found config.ru", 1),
+            evidence_if(path_exists(app_root, "Gemfile"), "found Gemfile", 4),
+            evidence_if(path_exists(app_root, "config.ru"), "found config.ru", 1),
         ]),
         build_detection("csharp", [
             evidence_if(any(name.endswith(".sln") or name.endswith(".csproj") for name in root_entries), "found .sln/.csproj", 4),
-            evidence_if(Path("Program.cs").exists(), "found Program.cs", 1),
+            evidence_if(path_exists(app_root, "Program.cs"), "found Program.cs", 1),
         ]),
     ]
     language_detections = [item for item in language_detections if item["score"] >= 2]
@@ -283,8 +350,8 @@ def scan_project():
     framework_details = [
         {**build_detection("next", [
             evidence_if(has_dependency(dep_names, "next"), "package.json -> next", 4),
-            evidence_if(Path("next.config.js").exists() or Path("next.config.mjs").exists() or Path("next.config.ts").exists(), "found next.config.*", 3),
-            evidence_if(Path("app").exists() or Path("pages").exists(), "found app/ or pages/", 1),
+            evidence_if(path_exists(app_root, "next.config.js") or path_exists(app_root, "next.config.mjs") or path_exists(app_root, "next.config.ts"), "found next.config.*", 3),
+            evidence_if(path_exists(app_root, "app") or path_exists(app_root, "pages"), "found app/ or pages/", 1),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("react", [
             evidence_if(has_dependency(dep_names, "react"), "package.json -> react", 4),
@@ -295,14 +362,14 @@ def scan_project():
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("nuxt", [
             evidence_if(has_dependency(dep_names, "nuxt"), "package.json -> nuxt", 4),
-            evidence_if(Path("nuxt.config.ts").exists() or Path("nuxt.config.js").exists(), "found nuxt.config.*", 3),
+            evidence_if(path_exists(app_root, "nuxt.config.ts") or path_exists(app_root, "nuxt.config.js"), "found nuxt.config.*", 3),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("svelte", [
             evidence_if(has_dependency(dep_names, "svelte", "@sveltejs/kit"), "package.json -> svelte", 4),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("angular", [
             evidence_if(has_dependency(dep_names, "@angular/core"), "package.json -> @angular/core", 4),
-            evidence_if(Path("angular.json").exists(), "found angular.json", 3),
+            evidence_if(path_exists(app_root, "angular.json"), "found angular.json", 3),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("express", [
             evidence_if(has_dependency(dep_names, "express"), "package.json -> express", 4),
@@ -315,34 +382,39 @@ def scan_project():
         ]), "kind": "backend", "project_type": "api", "language": "python"},
         {**build_detection("django", [
             evidence_if(text_matches(requirements, r"\bdjango\b") or text_matches(pyproject, r"\bdjango\b"), "Python deps -> django", 4),
-            evidence_if(Path("manage.py").exists(), "found manage.py", 2),
-        ]), "kind": "backend", "project_type": "api", "language": "python"},
+            evidence_if(path_exists(app_root, "manage.py"), "found manage.py", 2),
+            evidence_if(path_exists(app_root, "templates"), "found templates/", 1),
+        ]), "kind": "backend", "project_type": "web-app", "language": "python"},
         {**build_detection("flask", [
             evidence_if(text_matches(requirements, r"\bflask\b") or text_matches(pyproject, r"\bflask\b"), "Python deps -> flask", 4),
         ]), "kind": "backend", "project_type": "api", "language": "python"},
         {**build_detection("laravel", [
             evidence_if(has_composer_dependency(composer_dep_names, "laravel/framework"), "composer.json -> laravel/framework", 4),
-            evidence_if(Path("artisan").exists(), "found artisan", 3),
-        ]), "kind": "backend", "project_type": "api", "language": "php"},
+            evidence_if(path_exists(app_root, "artisan"), "found artisan", 3),
+            evidence_if(path_exists(app_root, "resources", "views"), "found resources/views", 1),
+        ]), "kind": "backend", "project_type": "web-app", "language": "php"},
         {**build_detection("cakephp", [
             evidence_if(has_composer_dependency(composer_dep_names, "cakephp/cakephp"), "composer.json -> cakephp/cakephp", 4),
-            evidence_if(Path("bin/cake").exists(), "found bin/cake", 3),
-            evidence_if(Path("config/app.php").exists(), "found config/app.php", 2),
-            evidence_if(Path("app/Config/core.php").exists(), "found app/Config/core.php (CakePHP legacy)", 3),
-            evidence_if(Path("app/Controller/AppController.php").exists(), "found app/Controller/AppController.php", 2),
-            evidence_if(Path("app/Model/AppModel.php").exists(), "found app/Model/AppModel.php", 2),
-            evidence_if(Path("lib/Cake").exists(), "found lib/Cake", 3),
-            evidence_if(Path("cake/console/cake").exists(), "found cake/console/cake", 3),
-        ]), "kind": "backend", "project_type": "api", "language": "php"},
+            evidence_if(path_exists(app_root, "bin", "cake"), "found bin/cake", 3),
+            evidence_if(path_exists(app_root, "config", "app.php"), "found config/app.php", 2),
+            evidence_if(path_exists(app_root, "app", "Config", "core.php"), "found app/Config/core.php (CakePHP legacy)", 3),
+            evidence_if(path_exists(app_root, "app", "Controller", "AppController.php"), "found app/Controller/AppController.php", 2),
+            evidence_if(path_exists(app_root, "app", "Model", "AppModel.php"), "found app/Model/AppModel.php", 2),
+            evidence_if(path_exists(app_root, "lib", "Cake"), "found lib/Cake", 3),
+            evidence_if(path_exists(app_root, "cake", "console", "cake"), "found cake/console/cake", 3),
+            evidence_if(path_exists(app_root, "app", "View"), "found app/View", 2),
+            evidence_if(any(p.suffix.lower() == ".ctp" for p in app_root.joinpath("app", "View").rglob("*.ctp")) if path_exists(app_root, "app", "View") else False, "found .ctp view templates", 2),
+        ]), "kind": "backend", "project_type": "web-app", "language": "php"},
         {**build_detection("symfony", [
             evidence_if(has_composer_dependency(composer_dep_names, "symfony/framework-bundle"), "composer.json -> symfony/framework-bundle", 4),
-            evidence_if(Path("bin/console").exists(), "found bin/console", 2),
-            evidence_if(Path("config/bundles.php").exists(), "found config/bundles.php", 1),
-        ]), "kind": "backend", "project_type": "api", "language": "php"},
+            evidence_if(path_exists(app_root, "bin", "console"), "found bin/console", 2),
+            evidence_if(path_exists(app_root, "config", "bundles.php"), "found config/bundles.php", 1),
+            evidence_if(path_exists(app_root, "templates"), "found templates/", 1),
+        ]), "kind": "backend", "project_type": "web-app", "language": "php"},
         {**build_detection("codeigniter", [
             evidence_if(has_composer_dependency(composer_dep_names, "codeigniter4/framework"), "composer.json -> codeigniter4/framework", 4),
-            evidence_if(Path("spark").exists(), "found spark", 2),
-            evidence_if(Path("app/Config/App.php").exists(), "found app/Config/App.php", 1),
+            evidence_if(path_exists(app_root, "spark"), "found spark", 2),
+            evidence_if(path_exists(app_root, "app", "Config", "App.php"), "found app/Config/App.php", 1),
         ]), "kind": "backend", "project_type": "api", "language": "php"},
         {**build_detection("gin", [
             evidence_if(text_matches(go_mod, r"\bgithub\.com\/gin-gonic\/gin\b"), "go.mod -> github.com/gin-gonic/gin", 4),
@@ -355,8 +427,9 @@ def scan_project():
         ]), "kind": "backend", "project_type": "api", "language": "go"},
         {**build_detection("rails", [
             evidence_if(text_matches(gemfile, r'^\s*gem\s+["\']rails["\']'), "Gemfile -> rails", 4),
-            evidence_if(Path("bin/rails").exists(), "found bin/rails", 2),
-        ]), "kind": "backend", "project_type": "api", "language": "ruby"},
+            evidence_if(path_exists(app_root, "bin", "rails"), "found bin/rails", 2),
+            evidence_if(path_exists(app_root, "app", "views"), "found app/views", 1),
+        ]), "kind": "backend", "project_type": "web-app", "language": "ruby"},
         {**build_detection("spring", [
             evidence_if(text_matches(pom, r"spring-boot") or text_matches(gradle, r"spring-boot"), "Java build -> spring-boot", 4),
         ]), "kind": "backend", "project_type": "api", "language": "java"},
@@ -366,8 +439,8 @@ def scan_project():
         ]), "kind": "backend", "project_type": "api", "language": "csharp"},
         {**build_detection("tauri", [
             evidence_if(has_dependency(dep_names, "@tauri-apps/api"), "package.json -> @tauri-apps/api", 4),
-            evidence_if(Path("src-tauri/tauri.conf.json").exists() or Path("src-tauri/tauri.conf.json5").exists(), "found src-tauri/tauri.conf.*", 4),
-            evidence_if(Path("src-tauri/Cargo.toml").exists(), "found src-tauri/Cargo.toml", 2),
+            evidence_if(path_exists(app_root, "src-tauri", "tauri.conf.json") or path_exists(app_root, "src-tauri", "tauri.conf.json5"), "found src-tauri/tauri.conf.*", 4),
+            evidence_if(path_exists(app_root, "src-tauri", "Cargo.toml"), "found src-tauri/Cargo.toml", 2),
         ]), "kind": "desktop", "project_type": "desktop", "language": "rust"},
         {**build_detection("axum", [
             evidence_if(text_matches(cargo, r"\baxum\b"), "Cargo.toml -> axum", 4),
@@ -404,9 +477,10 @@ def scan_project():
     if any(item["project_type"] == "desktop" for item in framework_details): project_type = "desktop"
     elif any(item["project_type"] == "mobile" for item in framework_details): project_type = "mobile"
     elif any(item["kind"] == "frontend" for item in framework_details) and any(item["kind"] == "backend" for item in framework_details): project_type = "fullstack"
+    elif any(item["project_type"] == "web-app" for item in framework_details): project_type = "web-app"
     elif any(item["kind"] == "backend" for item in framework_details): project_type = "api"
     elif any(item["kind"] == "frontend" for item in framework_details): project_type = "web-app"
-    elif Path("package.json").exists() and pkg.get("bin"): project_type = "cli"
+    elif path_exists(app_root, "package.json") and pkg.get("bin"): project_type = "cli"
     elif primary_language in ["php", "python", "go", "java", "ruby", "csharp", "rust"]: project_type = "api"
 
     if has_dependency(dep_names, "pg", "postgres", "@prisma/client") or "postgres" in json.dumps(pkg).lower(): database = "postgres"
@@ -421,26 +495,26 @@ def scan_project():
     elif has_dependency(dep_names, "pytest") or text_matches(requirements, r"\bpytest\b") or text_matches(pyproject, r"\bpytest\b"): test_framework = "pytest"
     elif has_composer_dependency(composer_dep_names, "phpunit/phpunit"): test_framework = "phpunit"
     elif has_composer_dependency(composer_dep_names, "pestphp/pest"): test_framework = "pest"
-    elif Path("go.mod").exists(): test_framework = "go test"
+    elif path_exists(app_root, "go.mod"): test_framework = "go test"
     elif text_matches(gemfile, r'^\s*gem\s+["\']rspec["\']'): test_framework = "rspec"
 
-    if Path("Dockerfile").exists() or Path("docker-compose.yml").exists() or Path("docker-compose.yaml").exists():
+    if repo_has_any(repo_root, [("Dockerfile",), ("docker-compose.yml",), ("docker-compose.yaml",)]):
         infrastructure.append("docker")
 
-    if Path("vercel.json").exists():
+    if repo_has_any(repo_root, [("vercel.json",)]):
         cloud = "vercel"
         infrastructure.append("vercel")
-    elif Path("fly.toml").exists():
+    elif repo_has_any(repo_root, [("fly.toml",)]):
         cloud = "fly"
         infrastructure.append("fly")
-    elif Path("railway.json").exists() or Path("railway.toml").exists():
+    elif repo_has_any(repo_root, [("railway.json",), ("railway.toml",)]):
         cloud = "railway"
         infrastructure.append("railway")
 
-    if Path(".github/workflows").exists(): ci_cd = "github-actions"
-    elif Path(".gitlab-ci.yml").exists(): ci_cd = "gitlab-ci"
-    elif Path(".circleci/config.yml").exists(): ci_cd = "circleci"
-    elif Path("Jenkinsfile").exists(): ci_cd = "jenkins"
+    if repo_has_any(repo_root, [(".github", "workflows")], max_depth=2): ci_cd = "github-actions"
+    elif repo_has_any(repo_root, [(".gitlab-ci.yml",)], max_depth=2): ci_cd = "gitlab-ci"
+    elif repo_has_any(repo_root, [(".circleci", "config.yml")], max_depth=2): ci_cd = "circleci"
+    elif repo_has_any(repo_root, [("Jenkinsfile",)], max_depth=2): ci_cd = "jenkins"
 
     scan_evidence = []
     if language_detections:
@@ -449,6 +523,7 @@ def scan_project():
 
     return {
         "project_name": Path.cwd().name,
+        "app_root": str(app_root.relative_to(repo_root)) if app_root != repo_root else ".",
         "description": pkg.get("description") or composer.get("description", "A software project"),
         "project_type": project_type if project_type in PROJECT_TYPES_ALL else "web-app",
         "primary_language": primary_language if primary_language in LANGUAGES_ALL else "typescript",
@@ -456,7 +531,7 @@ def scan_project():
         "framework_details": framework_details,
         "scan_evidence": scan_evidence,
         "database": database if database in DATABASES_ALL else "none",
-        "package_manager": detect_package_manager(),
+        "package_manager": detect_package_manager(app_root),
         "uses_docker": "docker" in infrastructure,
         "cloud": cloud,
         "infrastructure": uniq(infrastructure),
@@ -539,21 +614,33 @@ These detections were inferred from the current codebase during `init --scan`:
 # Generated by thachvd-kit init wizard on {datetime.now().strftime('%Y-%m-%d')}
 # Edit freely — this is your project's brain.
 
-## Project
-
-- **Name:** {data['project_name']}
-- **Description:** {data['description']}
-- **Type:** {data['project_type']}
-
----
+## Project
+
+- **Name:** {data['project_name']}
+- **Description:** {data['description']}
+- **Type:** {data['project_type']}
+
+---
+
+## Context Status
+
+```yaml
+context:
+  status: {data.get('context_status', 'baseline')}
+  needs_ai_refinement: {'true' if data.get('needs_ai_refinement') else 'false'}
+  last_refined_at: {data.get('last_refined_at', 'not-yet-refined')}
+```
+
+---
 
 ## Stack
 
 ```yaml
-stack:
-  primary_language: {data['primary_language']}
-  frameworks: [{', '.join(frameworks)}]
-  database: {data.get('database', 'none')}
+stack:
+  app_root: {data.get('app_root', '.')}
+  primary_language: {data['primary_language']}
+  frameworks: [{', '.join(frameworks)}]
+  database: {data.get('database', 'none')}
   infrastructure: [{', '.join(infrastructure)}]
   package_manager: {data.get('package_manager', 'auto-detect')}
   test_framework: {data.get('test_framework', 'auto-detect')}
@@ -699,6 +786,20 @@ When done, summarize:
 - what is still inferred
 - which files provided the strongest evidence
 """
+
+def format_scan_preview_lines(scanned):
+    return [
+        ("App root", scanned.get("app_root", ".")),
+        ("Project type", scanned.get("project_type", "unknown")),
+        ("Primary language", scanned.get("primary_language", "unknown")),
+        ("Frameworks", ", ".join(scanned.get("frameworks", [])) or "no framework"),
+        ("Database", scanned.get("database", "none")),
+        ("Package manager", scanned.get("package_manager", "auto-detect")),
+        ("Test framework", scanned.get("test_framework", "auto-detect")),
+        ("Cloud", scanned.get("cloud", "none")),
+        ("Infrastructure", ", ".join(scanned.get("infrastructure", [])) or "none"),
+        ("CI/CD", scanned.get("ci_cd", "none")),
+    ]
 
 # ─── Main wizard ─────────────────────────────────────────────────────────────
 
@@ -739,8 +840,10 @@ def main():
     review_scanned_fields = not use_scan
     if use_scan:
         print(f"  {dim('Scan mode: detecting stack from current project files...')}")
-        print(f"  {bold('Scan result:')} {scanned['primary_language']} | {', '.join(scanned['frameworks']) or 'no framework'}")
-        print(f"  {bold('Detected infra:')} {', '.join(scanned['infrastructure']) or 'none'}\n")
+        print(f"  {bold('Detected context:')}")
+        for label, value in format_scan_preview_lines(scanned):
+            print(f"    · {label}: {value}")
+        print()
         if scanned.get("scan_evidence"):
             print(f"  {bold('Evidence:')}")
             for line in scanned["scan_evidence"]:
@@ -830,6 +933,10 @@ def main():
     data["code_style"] = data.get("code_style", (scanned or {}).get("code_style", "project-standard"))
     data["framework_details"] = data.get("framework_details", (scanned or {}).get("framework_details", []))
     data["scan_evidence"] = data.get("scan_evidence", (scanned or {}).get("scan_evidence", []))
+    data["app_root"] = data.get("app_root", (scanned or {}).get("app_root", "."))
+    data["context_status"] = data.get("context_status", "baseline")
+    data["needs_ai_refinement"] = data.get("needs_ai_refinement", False)
+    data["last_refined_at"] = data.get("last_refined_at", "not-yet-refined")
     data["architecture_notes"] = data.get("architecture_notes", (scanned or {}).get("architecture_notes", "<!-- Add notes -->"))
     data["current_phase"] = data.get("current_phase", (scanned or {}).get("current_phase", "Initial setup"))
     data["next_phase"] = data.get("next_phase", (scanned or {}).get("next_phase", "—"))
@@ -838,6 +945,9 @@ def main():
     if data["uses_docker"]: data["infrastructure"].append("docker")
     if data["cloud"] != "none": data["infrastructure"].append(data["cloud"])
 
+    if not args.yes:
+        data["needs_ai_refinement"] = ask_bool("Should the agent refine PROJECT_CONTEXT.md on first session start?", default=use_scan)
+
     # ── Generate files ────────────────────────────────────────────────────
     section("Generating Files")
 
@@ -853,7 +963,7 @@ def main():
         print(f"  {green('✓')} {bold('CLAUDE.md')} generated (Claude Code / Codex)")
 
     ai_refine_path = None
-    if not args.yes and ask_bool("Generate AI context refinement prompt?", default=use_scan):
+    if data.get("needs_ai_refinement"):
         ai_refine_path = Path("AI_CONTEXT_REFINEMENT.md")
         ai_refine_path.write_text(generate_ai_context_refinement_prompt(data), encoding="utf-8")
         print(f"  {green('✓')} {bold('AI_CONTEXT_REFINEMENT.md')} generated")