thachvd-kit 1.0.24 → 1.0.26

package/bin/cli.js

@@ -1,11 +1,11 @@
 #!/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 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();
@@ -63,7 +63,7 @@ const INFRA_SKILLS = {
     vercel: ["deployment-procedures"],
 };
 
-function resolveSkills(data) {
+function resolveSkills(data) {
     const skills = new Set();
     const lang = (data.primary_language || "").toLowerCase();
 
@@ -88,16 +88,16 @@ function resolveSkills(data) {
     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();
-}
+    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',
@@ -120,59 +120,59 @@ const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'bu
 
 function printHelp() {
     console.log(`
-${pc.bold('Usage:')}
-  thachvd-kit [--yes]
-  thachvd-kit init [--yes]
-  thachvd-kit --version
-  thachvd-kit --help
-
-${pc.bold('Commands:')}
-  init      Bootstrap shared AI-agent rules and tooling
-
-${pc.bold('Options:')}
-  --yes     Overwrite generated files when they already exist
-  --no-setup-mcp Skip local Codegraph and Playwright MCP setup
-  --version Show the installed CLI version
-  --help    Show this help message
-
-${pc.bold('What gets generated:')}
-  AGENTS.md   Shared instructions for Codex, Antigravity, Claude Code, and Cursor
-  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/     Shared docs, skills, workflows, agents, and rules
-  ~/.codex/skills/  Selected Codex skills copied to global user dir (shows in $ menu)
-  .claude/skills/   Selected Claude Code project skills copied from .agent/skills
-
-${pc.bold('Workflow guide:')}
-  Idea is fuzzy            /brainstorm  Explore options, tradeoffs, and recommended direction
-  New app from scratch     /create      Turn an app idea into plan + implementation flow
-  Feature is clear         /plan        Create docs/PLAN-*.md first, no code yet
-  Existing app update      /enhance     Add or change a feature in an existing codebase
-  Bug or failing behavior  /debug       Investigate symptoms, hypotheses, root cause, fix
-  UI / UX work             ui-ux-pro-max, frontend-specialist, $frontend-design, $webapp-testing
-  Run or add tests         /test        Generate tests, run tests, check coverage
-  Preview locally          /preview     Start, stop, restart, or health-check dev server
-  Deploy / infra           /deploy      Release, hosting, Docker, cloud, environment setup
-  Project state            /status      Summarize stack, progress, preview, pending work
-  Multi-domain work        /orchestrate Coordinate frontend, backend, data, security, QA
-
-${pc.bold('Common explicit skill prompts:')}
-  Use /brainstorm for this feature idea before planning.
-  Use /plan for this feature; do not write code yet.
-  Use /enhance to implement this planned feature.
-  Use $clean-code before editing this module.
-  Use $systematic-debugging to investigate this bug.
-  Use $webapp-testing to verify the UI with Playwright.
-  Use $verification-before-completion before claiming done.
-  Use $writing-skills to improve a SKILL.md description.
-
-${pc.bold('Tip:')}
-  Skills are copied for Codex/Claude, but you can call them explicitly with $skill-name
-  when implicit matching does not fire.
-`);
-
-}
+${pc.bold('Usage:')}
+  thachvd-kit [--yes]
+  thachvd-kit init [--yes]
+  thachvd-kit --version
+  thachvd-kit --help
+
+${pc.bold('Commands:')}
+  init      Bootstrap shared AI-agent rules and tooling
+
+${pc.bold('Options:')}
+  --yes     Overwrite generated files when they already exist
+  --no-setup-mcp Skip local Codegraph and Playwright MCP setup
+  --version Show the installed CLI version
+  --help    Show this help message
+
+${pc.bold('What gets generated:')}
+  AGENTS.md   Shared instructions for Codex, Antigravity, Claude Code, and Cursor
+  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/     Shared docs, skills, workflows, agents, and rules
+  ~/.codex/skills/  Selected Codex skills copied to global user dir (shows in $ menu)
+  .claude/skills/   Selected Claude Code project skills copied from .agent/skills
+
+${pc.bold('Workflow guide:')}
+  Idea is fuzzy            /brainstorm  Explore options, tradeoffs, and recommended direction
+  New app from scratch     /create      Turn an app idea into plan + implementation flow
+  Feature is clear         /plan        Create docs/PLAN-*.md first, no code yet
+  Existing app update      /enhance     Add or change a feature in an existing codebase
+  Bug or failing behavior  /debug       Investigate symptoms, hypotheses, root cause, fix
+  UI / UX work             ui-ux-pro-max, frontend-specialist, $frontend-design, $webapp-testing
+  Run or add tests         /test        Generate tests, run tests, check coverage
+  Preview locally          /preview     Start, stop, restart, or health-check dev server
+  Deploy / infra           /deploy      Release, hosting, Docker, cloud, environment setup
+  Project state            /status      Summarize stack, progress, preview, pending work
+  Multi-domain work        /orchestrate Coordinate frontend, backend, data, security, QA
+
+${pc.bold('Common explicit skill prompts:')}
+  Use /brainstorm for this feature idea before planning.
+  Use /plan for this feature; do not write code yet.
+  Use /enhance to implement this planned feature.
+  Use $clean-code before editing this module.
+  Use $systematic-debugging to investigate this bug.
+  Use $webapp-testing to verify the UI with Playwright.
+  Use $verification-before-completion before claiming done.
+  Use $writing-skills to improve a SKILL.md description.
+
+${pc.bold('Tip:')}
+  Skills are copied for Codex/Claude, but you can call them explicitly with $skill-name
+  when implicit matching does not fire.
+`);
+
+}
 
 function formatScanPreviewLines(scanned) {
     return [
@@ -886,855 +886,872 @@ function resolveAgentTable(data) {
     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 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.
-5. Read \`.agent/docs/tooling.md\` when the task needs Playwright, codegraph, MCP, or native Codex/Claude skill setup.
-6. Select and load only the agent, skill, or workflow files that match the current task.
-
-If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
-
-## Task Flow
-
-- Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
-- Simple fix: inspect dependencies, make the smallest change, run focused verification.
-- Feature or refactor: define success criteria, make a short plan, implement, then verify.
-- Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
-- UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
-
-## Skill Loading
-
-- Treat \`.agent/skills/\` as the shared source of truth for all kit skills.
-- Codex exposes skills from \`~/.codex/skills/\` in the \`$\` menu; \`thachvd-kit\` copies selected skills there on init.
-- Claude Code project skills live in \`.claude/skills/\`.
-- If a skill is missing from the global dir, fall back to the matching \`.agent/skills/<skill>/SKILL.md\` file.
-- Do not load skill bodies by default; load a skill only when the user mentions it, the task clearly matches its description, or \`.agent/docs/project.md\` routes the task to it.
-- Prefer explicit skill mentions for predictable behavior: \`$clean-code\`, \`$systematic-debugging\`, \`$webapp-testing\`, or any skill listed in \`.agent/docs/project.md\`.
-- Run \`thachvd-kit --help\` to see common workflow and skill recommendations.
-- When creating or improving skills, use \`writing-skills\` first and make the \`description\` field specific enough for implicit invocation.
-
-## 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 using MCP server tools (e.g., \`codegraph\` for codebase search/symbol tracking, \`context7\` for API/docs queries, and \`playwright\` for browser/UI testing and verification) to explore, search, and verify rather than recursively listing directories, running expensive shell commands/grep, or reading large files. This minimizes token usage and maintains a cleaner context.
-- 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 docs: \`.agent/docs/\`
-- Specialist agents: \`.agent/agents/\`
-- Skills: \`.agent/skills/\`
-- Codex global skills: \`~/.codex/skills/\` (installed by thachvd-kit init)
-- Claude Code project skills: \`.claude/skills/\`
-- Workflows: \`.agent/workflows/\`
-- Tooling setup: \`.agent/docs/tooling.md\`
-- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
-- Cursor entry rules: \`.cursorrules\`
-`;
-}
-
-function generateSharedClaudeMd(data) {
-    return `@AGENTS.md
-
-${generateSharedAgentsMd(data)}
-
-## 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/.
-
----
-
-${generateSharedAgentsMd(data)}
-`;
-}
-
-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 agentRows = resolveAgentTable(data).map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
-    const skillsList = resolveSkills(data).map(s => `- ${s}`).join('\n');
-    const evidence = (data.scan_evidence || []).length > 0
-        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
-        : '- TODO: refine scan evidence by inspecting the project.';
-
-    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}\`
-
-## Agent Routing
-
-| Task Type | Agent | Primary Skills |
-|-----------|-------|----------------|
-${agentRows}
-
-## Auto-Resolved Skills
-
-${skillsList}
-
-## Scan Evidence
-
-${evidence}
-`;
-}
-
-function generateArchitectureDoc(data) {
-    const appRootLine = data.app_root && data.app_root !== '.'
-        ? `- App root is currently detected as \`${data.app_root}\`.`
-        : '- App root is the repository root unless refined below.';
-    const evidence = (data.scan_evidence || []).length > 0
-        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
-        : '- TODO: refine architecture by scanning source directories.';
-
-    return `# Architecture Notes
-
-## Current Map
-
-${appRootLine}
-- TODO: refine major directories and responsibilities.
-- TODO: refine main entry points, routing, state boundaries, and integration boundaries.
-
-## Detected Evidence
-
-${evidence}
-
-## AI Maintenance Rule
-
-Before non-trivial implementation work, inspect this file. If it is stale or still contains TODO items relevant to the task, update it from the code before editing product code.
-`;
-}
-
-function generateConventionsDoc(data) {
-    return `# Coding Conventions
-
-## Current Standards
-
-- Maximum file length: ${data.max_file_lines || '300'} lines unless the existing project standard is stricter.
-- Code comments and identifiers should be written in English.
-- Keep changes scoped to the user request.
-- Prefer existing local patterns over introducing new abstractions.
-- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
-
-## Verification
-
-- Run the focused test or lint command that matches the touched area.
-- If no automated check exists, document the manual verification performed.
-- 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
-
-## Before Every Task
-
-1. Read AGENTS.md.
-2. Read .agent/docs/project.md.
-3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
-4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
-5. Check if MCP servers (like \`codegraph\`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
-
-## Skill Selection
-
-- Prefer native skill discovery when the client exposes it.
-- Codex global skills live in ~/.codex/skills/ and are visible via the $ menu; thachvd-kit copies selected skills there on init.
-- Claude Code project skills live in .claude/skills.
-- Shared fallback skills live in .agent/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
-
-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.
-
-## 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 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);
-
-    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 -- npx -y @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 = "npx"
-args = ["-y", "@upstash/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 = "npx"
-args = ["-y", "@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": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "command": "npx",
-      "args": ["-y", "@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": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    },
-    "filesystem": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@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;
-    let skipped = 0;
-
-    function copyDir(src, dest) {
-        fs.mkdirSync(dest, { recursive: true });
-        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-            const srcPath = path.join(src, entry.name);
-            const destPath = path.join(dest, entry.name);
-            const relativeSrc = path.relative(srcAgent, srcPath).split(path.sep).join('/');
-            if (relativeSrc === 'docs' || relativeSrc.startsWith('docs/')) {
-                continue;
-            }
-            if (entry.isDirectory()) {
-                copyDir(srcPath, destPath);
-            } else {
-                if (fs.existsSync(destPath)) {
-                    skipped++;
-                } else {
-                    fs.copyFileSync(srcPath, destPath);
-                    copied++;
-                }
-            }
-        }
-    }
-
-    copyDir(srcAgent, destAgent);
-    return { copied, skipped };
-}
-
-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 skipped = 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 if (fs.existsSync(destPath) && !assumeYes) {
-                skipped++;
-            } 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, missing, skills: selectedSkills };
-}
-
-async function writeGeneratedFile(relativePath, content, assumeYes) {
-    const outputPath = path.join(targetDir, relativePath);
-    const exists = fs.existsSync(outputPath);
-    if (exists && !assumeYes) 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;
-}
-
-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;
-}
-
-function ensureCodegraphCli() {
-    if (commandExists('codegraph')) {
-        return { ok: true, message: 'codegraph CLI already installed' };
-    }
-    if (!commandExists('npm')) {
-        return { ok: false, message: 'npm not found; run: npm install -g @colbymchenry/codegraph' };
-    }
-    const result = spawnSync('npm', ['install', '-g', '@colbymchenry/codegraph'], {
-        encoding: 'utf8',
-        stdio: 'pipe'
-    });
-    if (result.status !== 0) {
-        return { ok: false, message: 'failed to install codegraph; run: npm install -g @colbymchenry/codegraph' };
-    }
-    return { ok: true, message: 'installed codegraph CLI' };
-}
-
-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 npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    const baseServers = {
-        codegraph: { command: 'codegraph', args: ['serve', '--mcp'] },
-        playwright: { command: npxCmd, args: ['-y', '@playwright/mcp'] },
-        context7: { command: npxCmd, args: ['-y', '@upstash/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 = [];
-    const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    if (!/\[mcp_servers\.context7\]/.test(existing)) {
-        blocks.push(`[mcp_servers.context7]
-command = "${npxCmd}"
-args = ["-y", "@upstash/context7-mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.codegraph\]/.test(existing)) {
-        blocks.push(`[mcp_servers.codegraph]
-command = "codegraph"
-args = ["serve", "--mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.playwright\]/.test(existing)) {
-        blocks.push(`[mcp_servers.playwright]
-command = "${npxCmd}"
-args = ["-y", "@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 context7, codegraph, playwright MCP in ${filePath}` };
-}
-
-function setupMcpServers() {
-    const results = [];
-    results.push(ensureCodegraphCli());
-
-    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;
-    }
-
-    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);
-
-    const shouldSetupMcp = !skipMcpSetup;
-
-    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
-
-    // Shared entry files are written after the .agent folder is available.
-
-    // Copy .agent folder
-    const { copied, skipped } = copyAgentFolder();
-    if (copied > 0) {
-        console.log(`  ${pc.green('OK')} Copied ${pc.bold('.agent/')} (${copied} file${copied !== 1 ? 's' : ''} added${skipped > 0 ? `, ${skipped} skipped` : ''})`);
-    } else if (skipped > 0) {
-        console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
-    }
-
-    const nativeSkills = copySelectedSkillFolders(data, assumeYes);
-    if (nativeSkills.copied > 0) {
-        console.log(`  ${pc.green('OK')} Copied native skills to ${pc.bold('~/.codex/skills/')} and ${pc.bold('.claude/skills/')} (${nativeSkills.skills.join(', ')})`);
-    } else if (nativeSkills.skipped > 0) {
-        console.log(`  ${pc.yellow('~')} Native skills already exist - ${nativeSkills.skipped} file${nativeSkills.skipped !== 1 ? 's' : ''} skipped`);
-    }
-
-
-    const generatedFiles = [
-        ['AGENTS.md', generateSharedAgentsMd(data)],
-        ['CLAUDE.md', generateSharedClaudeMd(data)],
-        ['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)]
-    ];
-
-    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
-    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
-    - ${pc.bold('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
-    - ${pc.bold('.claude/skills/')} selected Claude Code native skills
-
-  ${pc.bold('MCP/tooling setup:')}
-    - Codegraph CLI checked or installed; MCP configured for Codex, Gemini/Antigravity, and Claude Code
-    - Context7 MCP configured for Codex and Gemini/Antigravity
-    - Playwright MCP configured for Codex, Gemini/Antigravity, and Claude Code
-    - Browser install hint: ${pc.bold(resolveToolingSetup(data).playwrightCommand)}
-    - Codegraph index hint: run ${pc.bold('codegraph init -i')} when a project index is missing, then keep ${pc.bold('.codegraph/')} uncommitted
-
-  ${pc.bold('Next steps:')}
-    1. Copy the prompt below into your AI editor and describe what the project does
-    2. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, and ${pc.bold('.agent/')}
-    3. Open the project in Codex, Antigravity, Claude Code, or Cursor
-
-  ${pc.bold('Copy this prompt into your AI editor:')}
-${pc.dim('---')}
-Read AGENTS.md and all files under .agent/docs/.
-Ask me what this project does and any important conventions I want preserved.
-Then scan this repository.
-Update AGENTS.md, .cursorrules and .agent/docs/project.md, .agent/docs/architecture.md, .agent/docs/conventions.md, .agent/docs/workflow.md, and .agent/docs/tooling.md with factual project-specific rules.
-Do not implement product code.
-Remove TODO: refine only when backed by evidence from the codebase.
-${pc.dim('---')}
-`);
-}
-
-main().catch(err => {
-    console.error(pc.red('\nError during init:'), err);
-    process.exit(1);
-});
+
    return rows;
+}
+// --- 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.
+5. Read \`.agent/docs/tooling.md\` when the task needs Playwright, codegraph, MCP, or native Codex/Claude skill setup.
+6. Select and load only the agent, skill, or workflow files that match the current task.
+
+If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
+
+## Task Flow
+
+- Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
+- Simple fix: inspect dependencies, make the smallest change, run focused verification.
+- Feature or refactor: define success criteria, make a short plan, implement, then verify.
+- Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
+- UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
+
+## Skill Loading
+
+- Treat \`.agent/skills/\` as the shared source of truth for all kit skills.
+- Codex exposes skills from \`~/.codex/skills/\` in the \`$\` menu; \`thachvd-kit\` copies selected skills there on init.
+- Claude Code project skills live in \`.claude/skills/\`.
+- If a skill is missing from the global dir, fall back to the matching \`.agent/skills/<skill>/SKILL.md\` file.
+- Do not load skill bodies by default; load a skill only when the user mentions it, the task clearly matches its description, or \`.agent/docs/project.md\` routes the task to it.
+- Prefer explicit skill mentions for predictable behavior: \`$clean-code\`, \`$systematic-debugging\`, \`$webapp-testing\`, or any skill listed in \`.agent/docs/project.md\`.
+- Run \`thachvd-kit --help\` to see common workflow and skill recommendations.
+- When creating or improving skills, use \`writing-skills\` first and make the \`description\` field specific enough for implicit invocation.
+
+## 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 using MCP server tools (e.g., \`codegraph\` for codebase search/symbol tracking, \`context7\` for API/docs queries, and \`playwright\` for browser/UI testing and verification) to explore, search, and verify rather than recursively listing directories, running expensive shell commands/grep, or reading large files. This minimizes token usage and maintains a cleaner context.
+- 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 docs: \`.agent/docs/\`
+- Specialist agents: \`.agent/agents/\`
+- Skills: \`.agent/skills/\`
+- Codex global skills: \`~/.codex/skills/\` (installed by thachvd-kit init)
+- Claude Code project skills: \`.claude/skills/\`
+- Workflows: \`.agent/workflows/\`
+- Tooling setup: \`.agent/docs/tooling.md\`
+- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
+- Cursor entry rules: \`.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) {
+    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/.
+
+---
+
+${generateSharedAgentsMd(data)}
+`;
+}
+
+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 agentRows = resolveAgentTable(data).map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
+    const skillsList = resolveSkills(data).map(s => `- ${s}`).join('\n');
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine scan evidence by inspecting the project.';
+
+    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 MCP Tools
+
+Use these tools as first-class search and verification methods — prefer them over shell commands or file reads.
+
+| MCP | When to Use |
+|-----|-------------|
+| \`codegraph\` | Explore symbols, trace call chains, find usages — use BEFORE reading files |
+| \`context7\` | Look up library/framework docs, API signatures, migration guides |
+| \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
+
+> Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
+
+## Agent Routing
+
+| Task Type | Agent | Primary Skills |
+|-----------|-------|----------------|
+${agentRows}
+
+## Auto-Resolved Skills
+
+${skillsList}
+
+## Scan Evidence
+
+${evidence}
+`;
+}
+
+function generateArchitectureDoc(data) {
+    const appRootLine = data.app_root && data.app_root !== '.'
+        ? `- App root is currently detected as \`${data.app_root}\`.`
+        : '- App root is the repository root unless refined below.';
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine architecture by scanning source directories.';
+
+    return `# Architecture Notes
+
+## Current Map
+
+${appRootLine}
+- TODO: refine major directories and responsibilities.
+- TODO: refine main entry points, routing, state boundaries, and integration boundaries.
+
+## Detected Evidence
+
+${evidence}
+
+## AI Maintenance Rule
+
+Before non-trivial implementation work, inspect this file. If it is stale or still contains TODO items relevant to the task, update it from the code before editing product code.
+`;
+}
+
+function generateConventionsDoc(data) {
+    return `# Coding Conventions
+
+## Current Standards
+
+- Maximum file length: ${data.max_file_lines || '300'} lines unless the existing project standard is stricter.
+- Code comments and identifiers should be written in English.
+- Keep changes scoped to the user request.
+- Prefer existing local patterns over introducing new abstractions.
+- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
+
+## Verification
+
+- Run the focused test or lint command that matches the touched area.
+- If no automated check exists, document the manual verification performed.
+- 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
+
+## Before Every Task
+
+1. Read AGENTS.md.
+2. Read .agent/docs/project.md.
+3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
+4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
+5. Check if MCP servers (like \`codegraph\`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
+
+## Skill Selection
+
+- Prefer native skill discovery when the client exposes it.
+- Codex global skills live in ~/.codex/skills/ and are visible via the $ menu; thachvd-kit copies selected skills there on init.
+- Claude Code project skills live in .claude/skills.
+- Shared fallback skills live in .agent/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
+
+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.
+
+## 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 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);
+
+    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 };
+}
+
+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;
+}
+
+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;
+}
+
+function ensureGlobalNpmPackage(binaryName, packageName) {
+    if (commandExists(binaryName)) {
+        return { ok: true, message: `${binaryName} already installed` };
+    }
+    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}` };
+}
+
+function ensureCodegraphCli() {
+    return ensureGlobalNpmPackage('codegraph', '@colbymchenry/codegraph');
+}
+
+function ensureContext7Cli() {
+    return ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp');
+}
+
+function ensurePlaywrightMcpCli() {
+    return ensureGlobalNpmPackage('playwright-mcp', '@playwright/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 = {
+        codegraph: { command: 'codegraph', args: ['serve', '--mcp'] },
+        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 (!/\[mcp_servers\.codegraph\]/.test(existing)) {
+        blocks.push(`[mcp_servers.codegraph]
+command = "codegraph"
+args = ["serve", "--mcp"]
+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');
+    return { ok: true, message: `configured context7, codegraph, playwright MCP in ${filePath}` };
+}
+
+function setupMcpServers() {
+    const results = [];
+    results.push(ensureCodegraphCli());
+    results.push(ensureContext7Cli());
+    results.push(ensurePlaywrightMcpCli());
+
+    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;
+    }
+
+    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);
+
+    const shouldSetupMcp = !skipMcpSetup;
+
+    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
+
+    // Shared entry files are written after the .agent folder is available.
+
+    // Copy .agent folder
+    const { copied, skipped } = copyAgentFolder();
+    if (copied > 0) {
+        console.log(`  ${pc.green('OK')} Copied ${pc.bold('.agent/')} (${copied} file${copied !== 1 ? 's' : ''} added${skipped > 0 ? `, ${skipped} skipped` : ''})`);
+    } else if (skipped > 0) {
+        console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
+    }
+
+    const nativeSkills = copySelectedSkillFolders(data, assumeYes);
+    if (nativeSkills.copied > 0) {
+        console.log(`  ${pc.green('OK')} Copied native skills to ${pc.bold('~/.codex/skills/')} and ${pc.bold('.claude/skills/')} (${nativeSkills.skills.join(', ')})`);
+    } else if (nativeSkills.skipped > 0) {
+        console.log(`  ${pc.yellow('~')} Native skills already exist - ${nativeSkills.skipped} file${nativeSkills.skipped !== 1 ? 's' : ''} skipped`);
+    }
+
+
+    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)]
+    ];
+
+    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
+    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
+    - ${pc.bold('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
+    - ${pc.bold('.claude/skills/')} selected Claude Code native skills
+
+  ${pc.bold('MCP/tooling setup:')}
+    - Codegraph CLI checked or installed; MCP configured for Codex, Gemini/Antigravity, and Claude Code
+    - Context7 MCP configured for Codex and Gemini/Antigravity
+    - Playwright MCP configured for Codex, Gemini/Antigravity, and Claude Code
+    - Browser install hint: ${pc.bold(resolveToolingSetup(data).playwrightCommand)}
+    - Codegraph index hint: run ${pc.bold('codegraph init -i')} when a project index is missing, then keep ${pc.bold('.codegraph/')} uncommitted
+
+  ${pc.bold('Next steps:')}
+    1. Copy the prompt below into your AI editor and describe what the project does
+    2. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, and ${pc.bold('.agent/')}
+    3. Open the project in Codex, Antigravity, Claude Code, or Cursor
+
+  ${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/.
+Ask me what this project does and any important conventions I want preserved.
+Then scan this repository.
+Update CLAUDE.md, AGENTS.md, .cursorrules and .agent/docs/project.md, .agent/docs/architecture.md, .agent/docs/conventions.md, .agent/docs/workflow.md, and .agent/docs/tooling.md with factual project-specific rules.
+Do not implement product code.
+Remove TODO: refine only when backed by evidence from the codebase.
+${pc.dim('---')}
+`);
+}
+
+main().catch(err => {
+    console.error(pc.red('\nError during init:'), err);
+    process.exit(1);
+});