thachvd-kit 1.0.6 → 1.0.8

package/README.md

@@ -18,6 +18,7 @@ npx github:thachvd/thachvd-kit init
 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.
 
 ```bash
 thachvd-kit init --scan

package/bin/cli.js

@@ -126,6 +126,20 @@ ${pc.bold('Options:')}
 `);
 }
 
+function formatScanPreviewLines(scanned) {
+    return [
+        ['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: () => {
@@ -365,10 +379,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 +399,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 +419,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 +478,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)
         ])
     },
     {
@@ -563,7 +583,10 @@ function scanProject() {
         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')
+        programCsText: readTextIfExists('Program.cs'),
+        viewFilesText: fs.existsSync(path.join(targetDir, 'app', 'View'))
+            ? fs.readdirSync(path.join(targetDir, 'app', 'View'), { recursive: true }).join('\n')
+            : ''
     };
 
     const languageDetections = LANGUAGE_DETECTORS
@@ -605,6 +628,7 @@ 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';
@@ -745,13 +769,24 @@ ${(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
 
@@ -842,9 +877,73 @@ Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ')}
 - \`/test\` — Run test suite
 - \`/deploy\` — Deploy checklist
 
-See PROJECT_CONTEXT.md for full agent routing table.
-`;
-}
+See PROJECT_CONTEXT.md for full agent routing table.
+`;
+}
+
+function generateAiContextRefinementPrompt(data) {
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- No scan evidence was captured during init.';
+
+    return `# AI Context Refinement
+
+Use this prompt in your AI editor after \`thachvd-kit init\`.
+
+## Goal
+
+Refine \`PROJECT_CONTEXT.md\` so it reflects the real project more accurately than the baseline init scan.
+
+## Current Baseline
+
+- Project: ${data.project_name}
+- Type: ${data.project_type}
+- Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
+- Database: ${data.database || 'none'}
+- Infra: ${(data.infrastructure || []).join(', ') || 'none'}
+
+## Scan Evidence
+
+${evidence}
+
+## Instructions For The AI Agent
+
+1. Read \`PROJECT_CONTEXT.md\` first.
+2. Inspect the project selectively to improve factual accuracy.
+3. Prioritize:
+   - real database/config detection
+   - domain/capability inference
+   - architecture notes
+   - more accurate auto-resolved skills
+   - important project-specific constraints
+4. Update \`PROJECT_CONTEXT.md\` directly.
+5. Distinguish facts from inferences when uncertain.
+6. Do not implement product code in this pass. Only refine project context.
+
+## Suggested Files To Inspect
+
+- Root manifests: \`package.json\`, \`composer.json\`, \`Cargo.toml\`, \`pyproject.toml\`
+- Infrastructure/config: Docker, CI, env, framework config files
+- Database config and models
+- Main app entry points, routing, controllers/services
+- README and existing documentation
+
+## Desired Improvements
+
+- Correct the \`database\` field if config files reveal the real DB.
+- Add architecture notes that explain the actual structure.
+- Infer domain capabilities such as scraping, browser automation, external API integrations, queues, workers, etc.
+- Expand auto-resolved skills when there is clear evidence in the codebase.
+- Add caveats or assumptions if parts of the stack are still uncertain.
+
+## Completion Standard
+
+When done, summarize:
+- what was corrected
+- what is still inferred
+- which files provided the strongest evidence
+`;
+}
 
 // --- Main CLI ---
 
@@ -925,10 +1024,14 @@ async function main() {
 
     const scanned = useScan ? scanProject() : null;
     let reviewScannedFields = !useScan;
+    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}`));
@@ -1018,6 +1121,20 @@ 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 || [];
+
+    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);
@@ -1052,9 +1169,16 @@ async function main() {
     const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
     fs.writeFileSync(claudeMdPath, generateClaudeMd(data), 'utf8');
     console.log(`  ${pc.green('✓')} Generated ${pc.bold('CLAUDE.md')}`);
-
-    // Summary
-    const autoSkills = resolveSkills(data);
+
+    let aiRefinementPath = null;
+    if (requestAiRefinement) {
+        aiRefinementPath = path.join(targetDir, 'AI_CONTEXT_REFINEMENT.md');
+        fs.writeFileSync(aiRefinementPath, generateAiContextRefinementPrompt(data), 'utf8');
+        console.log(`  ${pc.green('✓')} Generated ${pc.bold('AI_CONTEXT_REFINEMENT.md')}`);
+    }
+
+    // Summary
+    const autoSkills = resolveSkills(data);
     console.log(`\n${pc.bold(pc.green('━━ Done! ━━'))}
   
   ${pc.bold('Project:')} ${data.project_name}
@@ -1067,11 +1191,12 @@ ${autoSkills.map(s => '    · ' + s).join('\n')}
   ${pc.bold('Generated files:')}
     · ${pc.bold(projectContextPath)}
     · ${pc.bold(claudeMdPath)}
+${aiRefinementPath ? `    · ${pc.bold(aiRefinementPath)}` : ''}
 
   ${pc.bold('Next steps:')}
     1. Your kit is installed in ${pc.bold('./.agent')}
     2. Review ${pc.bold('PROJECT_CONTEXT.md')} first and add architecture notes
-    3. Instruct the agent to read/update ${pc.bold('PROJECT_CONTEXT.md')} before major tasks
+    3. ${aiRefinementPath ? `Open ${pc.bold('AI_CONTEXT_REFINEMENT.md')} in your AI editor to refine project context` : `Instruct the agent to read/update ${pc.bold('PROJECT_CONTEXT.md')} before major tasks`}
     4. Open project in Antigravity or Claude Code — the agent will read context on start
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.6",
+    "version": "1.0.8",
     "description": "Universal Agent Kit for Antigravity, Claude Code, and OpenCode",
     "bin": {
         "thachvd-kit": "./bin/cli.js"

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

@@ -316,14 +316,16 @@ def scan_project():
         {**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("templates").exists(), "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("resources/views").exists(), "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),
@@ -333,12 +335,15 @@ def scan_project():
             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("app/View").exists(), "found app/View", 2),
+            evidence_if(any(p.suffix.lower() == ".ctp" for p in Path("app/View").rglob("*.ctp")) if Path("app/View").exists() 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("templates").exists(), "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),
@@ -356,7 +361,8 @@ def scan_project():
         {**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("app/views").exists(), "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"},
@@ -404,6 +410,7 @@ 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"
@@ -539,13 +546,24 @@ 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
 
@@ -607,7 +625,7 @@ Based on your stack, these skills will be loaded automatically:
 {data.get('known_issues', '<!-- Add known issues or pending tasks -->')}
 """
 
-def generate_claude_md(data):
+def generate_claude_md(data):
     """Generate CLAUDE.md for Claude Code / Codex compatibility."""
     return f"""# CLAUDE.md — {data['project_name']}
 # Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
@@ -636,8 +654,82 @@ Stack: {data['primary_language']} | {', '.join(data.get('frameworks', []))}
 - `/test` — Run test suite
 - `/deploy` — Deploy checklist
 
-See PROJECT_CONTEXT.md for full agent routing table.
-"""
+See PROJECT_CONTEXT.md for full agent routing table.
+"""
+
+def generate_ai_context_refinement_prompt(data):
+    scan_evidence = data.get("scan_evidence", [])
+    evidence_block = "\n".join("- " + line for line in scan_evidence) if scan_evidence else "- No scan evidence was captured during init."
+    return f"""# AI Context Refinement
+
+Use this prompt in your AI editor after `thachvd-kit init`.
+
+## Goal
+
+Refine `PROJECT_CONTEXT.md` so it reflects the real project more accurately than the baseline init scan.
+
+## Current Baseline
+
+- Project: {data['project_name']}
+- Type: {data['project_type']}
+- Stack: {data['primary_language']} | {', '.join(data.get('frameworks', [])) or 'no framework'}
+- Database: {data.get('database', 'none')}
+- Infra: {', '.join(data.get('infrastructure', [])) or 'none'}
+
+## Scan Evidence
+
+{evidence_block}
+
+## Instructions For The AI Agent
+
+1. Read `PROJECT_CONTEXT.md` first.
+2. Inspect the project selectively to improve factual accuracy.
+3. Prioritize:
+   - real database/config detection
+   - domain/capability inference
+   - architecture notes
+   - more accurate auto-resolved skills
+   - important project-specific constraints
+4. Update `PROJECT_CONTEXT.md` directly.
+5. Distinguish facts from inferences when uncertain.
+6. Do not implement product code in this pass. Only refine project context.
+
+## Suggested Files To Inspect
+
+- Root manifests: `package.json`, `composer.json`, `Cargo.toml`, `pyproject.toml`
+- Infrastructure/config: Docker, CI, env, framework config files
+- Database config and models
+- Main app entry points, routing, controllers/services
+- README and existing documentation
+
+## Desired Improvements
+
+- Correct the `database` field if config files reveal the real DB.
+- Add architecture notes that explain the actual structure.
+- Infer domain capabilities such as scraping, browser automation, external API integrations, queues, workers, etc.
+- Expand auto-resolved skills when there is clear evidence in the codebase.
+- Add caveats or assumptions if parts of the stack are still uncertain.
+
+## Completion Standard
+
+When done, summarize:
+- what was corrected
+- what is still inferred
+- which files provided the strongest evidence
+"""
+
+def format_scan_preview_lines(scanned):
+    return [
+        ("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 ─────────────────────────────────────────────────────────────
 
@@ -678,8 +770,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"]:
@@ -769,6 +863,9 @@ 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["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", "—"))
@@ -777,6 +874,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")
 
@@ -788,11 +888,17 @@ def main():
     # CLAUDE.md (for Claude Code / Codex)
     if args.platform in ("claude", "all"):
         claude_path = Path("CLAUDE.md")
-        claude_path.write_text(generate_claude_md(data), encoding="utf-8")
-        print(f"  {green('✓')} {bold('CLAUDE.md')} generated (Claude Code / Codex)")
-
-    # Summary
-    auto_skills = resolve_skills(data)
+        claude_path.write_text(generate_claude_md(data), encoding="utf-8")
+        print(f"  {green('✓')} {bold('CLAUDE.md')} generated (Claude Code / Codex)")
+
+    ai_refine_path = None
+    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")
+
+    # Summary
+    auto_skills = resolve_skills(data)
     print(f"""
 {bold(green('━━ Done! ━━'))}
 
@@ -806,10 +912,11 @@ def main():
   {bold('Generated files:')}
     · {bold(str(output_path.resolve()))}
     · {bold(str(Path("CLAUDE.md").resolve())) if args.platform in ("claude", "all") else 'CLAUDE.md not generated for this platform'}
+    · {bold(str(ai_refine_path.resolve())) if ai_refine_path else 'AI_CONTEXT_REFINEMENT.md not generated'}
 
   {bold('Next steps:')}
     1. Review {bold('PROJECT_CONTEXT.md')} first and add architecture notes
-    2. Instruct the agent to read/update {bold('PROJECT_CONTEXT.md')} before major tasks
+    2. {"Open " + bold("AI_CONTEXT_REFINEMENT.md") + " in your AI editor to refine project context" if ai_refine_path else "Instruct the agent to read/update " + bold("PROJECT_CONTEXT.md") + " before major tasks"}
     3. Open project in your AI editor (Antigravity / Claude Code / Codex)
     4. The agent will read PROJECT_CONTEXT.md on session start