thachvd-kit 1.0.16 → 1.0.18

package/bin/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const prompts = require('prompts');
-const pc = require('picocolors');
-const packageJson = require('../package.json');
+const fs = require('fs');
+const path = require('path');
+const { 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();
@@ -62,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();
 
@@ -87,8 +88,16 @@ function resolveSkills(data) {
     skills.add("clean-code");
     skills.add("systematic-debugging");
 
-    return Array.from(skills).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',
@@ -111,28 +120,58 @@ const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'bu
 
 function printHelp() {
     console.log(`
-${pc.bold('Usage:')}
-  thachvd-kit init [--scan] [--yes]
-  thachvd-kit --version
-  thachvd-kit --help
-
-${pc.bold('Commands:')}
-  init      Run the project init wizard
-
-${pc.bold('Options:')}
-  --scan    Scan the current project to auto-detect stack
-  --yes     Use detected/default values without prompting
-  --version Show the installed CLI version
-  --help    Show this help message
-
-${pc.bold('What gets generated:')}
-  AGENTS.md   Shared instructions for Codex, Antigravity, and Claude Code
-  CLAUDE.md   Claude Code entry file that imports AGENTS.md
-  GEMINI.md   Antigravity entry file that points to AGENTS.md
-  .agent/     Shared docs, skills, workflows, agents, and rules
-`);
-
-}
+${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, and Claude Code
+  CLAUDE.md   Claude Code entry file that imports AGENTS.md
+  GEMINI.md   Antigravity entry file that points to AGENTS.md
+  .agent/     Shared docs, skills, workflows, agents, and rules
+  .agents/skills/  Selected Codex repo skills copied from .agent/skills
+  .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 [
@@ -800,7 +839,7 @@ function scanProject() {
         code_style: 'project-standard',
         architecture_notes: '<!-- Add notes -->',
         current_phase: 'Initial setup',
-        next_phase: '—',
+        next_phase: '-',
         known_issues: '<!-- None yet -->'
     };
 }
@@ -861,9 +900,10 @@ Shared operating instructions for Codex, Antigravity, and Claude Code.
 
 1. Read this file first.
 2. Read \`.agent/docs/project.md\` for detected stack, commands, and routing.
-3. Read \`.agent/docs/workflow.md\` for the task flow before editing.
-4. Read \`.agent/docs/architecture.md\` and \`.agent/docs/conventions.md\` before planning code changes.
-5. Load only the agent, skill, or workflow files that match the current task.
+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.
 
@@ -872,10 +912,20 @@ If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the doc
 - Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
 - Simple fix: inspect dependencies, make the smallest change, run focused verification.
 - Feature or refactor: define success criteria, make a short plan, implement, then verify.
-- Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
-- UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
-
-## Rules
+- 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 should discover native repo skills from \`.agents/skills/\`; Claude Code should discover project skills from \`.claude/skills/\`.
+- If native skill discovery is unavailable or stale, 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.
@@ -886,13 +936,16 @@ If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the doc
 
 ## Shared Knowledge
 
-- Project docs: \`.agent/docs/\`
-- Specialist agents: \`.agent/agents/\`
-- Skills: \`.agent/skills/\`
-- Workflows: \`.agent/workflows/\`
-- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
-`;
-}
+- Project docs: \`.agent/docs/\`
+- Specialist agents: \`.agent/agents/\`
+- Skills: \`.agent/skills/\`
+- Codex native skills: \`.agents/skills/\`
+- Claude Code project skills: \`.claude/skills/\`
+- Workflows: \`.agent/workflows/\`
+- Tooling setup: \`.agent/docs/tooling.md\`
+- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
+`;
+}
 
 function generateSharedClaudeMd() {
     return `@AGENTS.md
@@ -903,67 +956,67 @@ This repository uses AGENTS.md as the shared cross-agent entry file. Follow the
 `;
 }
 
-function generateSharedGeminiMd() {
-    return `# GEMINI.md
-
-Antigravity entry file for this project.
-
-Read AGENTS.md first, then follow the shared docs under .agent/docs/.
-`;
-}
-
-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) {
+function generateSharedGeminiMd() {
+    return `# GEMINI.md
+
+Antigravity entry file for this project.
+
+Read AGENTS.md first, then follow the shared docs under .agent/docs/.
+`;
+}
+
+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');
@@ -1060,17 +1113,28 @@ function generateConventionsDoc(data) {
 `;
 }
 
-function generateWorkflowDoc() {
+function generateWorkflowDoc() {
     return `# Agent Workflow
 
 ## Before Every Task
 
-1. Read AGENTS.md.
-2. Read .agent/docs/project.md.
-3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
-4. Read only the relevant docs under .agent/agents, .agent/skills, and .agent/workflows.
-
-## Implementation Flow
+1. 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, .agents/skills, .claude/skills, and .agent/workflows.
+
+## Skill Selection
+
+- Prefer native skill discovery when the client exposes it.
+- Codex repo skills live in .agents/skills.
+- 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.
@@ -1085,12 +1149,159 @@ function generateWorkflowDoc() {
 - 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.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"]
+    },
+    "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"]
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp"]
+    }
+  }
+}
+\`\`\`
+
+Common local path:
+
+- Claude Code: \`~/.claude.json\`
+
+## Native Skill Folders
+
+The shared kit skills live in \`.agent/skills/\`. Antigravity can use that folder directly, but Codex expects repo skills under \`.agents/skills/\` or user skills under \`~/.agents/skills/\`. Claude Code may require its own native skill location depending on the installed client.
+
+- Codex repo skills: \`.agents/skills/\`
+- Codex user skills: \`~/.agents/skills/\`
+- Codex may also keep installed/system skills under \`$CODEX_HOME/skills\` such as \`~/.codex/skills\`; treat that as local Codex state, not a repo folder to generate or commit.
+- Claude Code project skills commonly live under \`.claude/skills/\`.
+- \`thachvd-kit\` copies selected native skills to \`.agents/skills/\` and \`.claude/skills/\` based on the detected stack.
+- Keep \`.agent/skills/\` as the full shared source of truth committed with the repo.
+
+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() {
+function copyAgentFolder() {
     const srcAgent = path.join(sourceDir, '.agent');
     if (!fs.existsSync(srcAgent)) return { copied: 0, skipped: 0 };
 
@@ -1100,16 +1311,16 @@ function copyAgentFolder() {
 
     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 {
+        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 {
@@ -1120,31 +1331,193 @@ function copyAgentFolder() {
         }
     }
 
-    copyDir(srcAgent, destAgent);
-    return { copied, skipped };
-}
-
-async function writeGeneratedFile(relativePath, content, assumeYes) {
-    const outputPath = path.join(targetDir, relativePath);
-    const exists = fs.existsSync(outputPath);
-    if (exists && !assumeYes) {
-        const res = await askQuestions({
-            type: 'confirm',
-            name: 'overwrite',
-            message: `${relativePath} already exists. Overwrite?`,
-            initial: false
-        });
-        if (!res.overwrite) return false;
-    }
-
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-    fs.writeFileSync(outputPath, content, 'utf8');
-    return true;
-}
-
-// --- Main CLI ---
+    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);
+    const destinations = [
+        path.join(targetDir, '.agents', 'skills'),
+        path.join(targetDir, '.claude', 'skills')
+    ];
+    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, includeContext7 = 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: 'npx', args: ['-y', '@playwright/mcp'] }
+    };
+    if (includeContext7) {
+        baseServers.context7 = { command: 'npx', args: ['-y', '@upstash/context7-mcp'] };
+    }
+    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 = "npx"
+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 = "npx"
+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, true));
+
+    const antigravityIdeConfig = homePath('.gemini', 'antigravity-ide', 'mcp_config.json');
+    if (antigravityIdeConfig) results.push(mergeMcpJson(antigravityIdeConfig, false, true));
+
+    const antigravityConfig = homePath('.gemini', 'antigravity', 'mcp_config.json');
+    if (antigravityConfig && fs.existsSync(path.dirname(antigravityConfig))) {
+        results.push(mergeMcpJson(antigravityConfig, false, true));
+    }
+
+    const claudeConfig = homePath('.claude.json');
+    if (claudeConfig) results.push(mergeMcpJson(claudeConfig, true));
+
+    return results;
+}
+
+// --- Main CLI ---
 
-async function main() {
+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);
@@ -1165,137 +1538,42 @@ async function main() {
         process.exit(1);
     }
 
-    let useScan = args.includes('--scan');
-    const assumeYes = args.includes('--yes') || args.includes('-y');
-
-    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
-    console.log('  ' + pc.bold('thachvd-kit') + ' — Project Init Wizard');
-    console.log(`  Generates AGENTS.md + .agent/ folder${useScan ? ' (scan-assisted)' : ''}`);
-    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')) + '\n');
-
-    let projectSetup = 'new';
-    if (!useScan && !assumeYes) {
-        const modeAnswer = await askQuestions([
-            {
-                type: 'select',
-                name: 'project_setup',
-                message: 'Project already exists or are you starting fresh?',
-                choices: [
-                    { title: 'Existing project', value: 'existing' },
-                    { title: 'New project', value: 'new' }
-                ]
-            },
-            {
-                type: prev => prev === 'existing' ? 'select' : null,
-                name: 'existing_mode',
-                message: 'How should thachvd-kit build project rules?',
-                choices: [
-                    { title: 'Scan current project files', value: 'scan' },
-                    { title: 'Enter context manually', value: 'manual' }
-                ],
-                initial: 0
-            }
-        ]);
-        projectSetup = modeAnswer.project_setup || 'new';
-        useScan = modeAnswer.existing_mode === 'scan';
-    }
-
-    if (useScan) {
-        console.log(pc.dim('  Scan mode: detecting stack from current project files...\n'));
-    } else if (projectSetup === 'new') {
-        console.log(pc.dim('  Manual mode: asking for project context explicitly.\n'));
-    }
-
-    const scanned = useScan ? scanProject() : null;
-    let reviewScannedFields = !useScan;
-    let requestAiRefinement = false;
-
-    if (useScan) {
-        console.log(`  ${pc.bold('Detected context:')}`);
-        formatScanPreviewLines(scanned).forEach(([label, value]) => {
-            console.log(`    · ${label}: ${value}`);
-        });
-        console.log('');
-        if ((scanned.scan_evidence || []).length > 0) {
-            console.log(`  ${pc.bold('Evidence:')}`);
-            scanned.scan_evidence.forEach(line => console.log(`    · ${line}`));
-            console.log('');
-        }
-
-        if (!assumeYes) {
-            const scanAction = await askQuestions({
-                type: 'select',
-                name: 'scan_action',
-                message: 'Use detected context as-is or review fields manually?',
-                choices: [
-                    { title: 'Use detected context', value: 'accept' },
-                    { title: 'Review detected fields', value: 'review' }
-                ],
-                initial: 0
-            });
-            reviewScannedFields = scanAction.scan_action === 'review';
-        }
-    }
-
-    const { project_name, description, project_type } = await askQuestions([
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'project_name', message: 'Project name:', initial: scanned?.project_name || path.basename(targetDir) },
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'description', message: 'Short description:', initial: scanned?.description || 'A software project' },
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'project_type', message: 'Project type:',
-            choices: PROJECT_TYPE_CHOICES.map(value => ({ title: value, value })),
-            initial: Math.max(PROJECT_TYPE_CHOICES.indexOf(scanned?.project_type || 'web-app'), 0)
-        }
-    ]);
-
-    const { primary_language } = await askQuestions({
-        type: assumeYes || !reviewScannedFields ? null : 'select',
-        name: 'primary_language',
-        message: 'Primary language:',
-        choices: LANGUAGE_CHOICES.map(l => ({ title: l, value: l })),
-        initial: Math.max(LANGUAGE_CHOICES.indexOf(scanned?.primary_language || 'typescript'), 0)
-    });
-
-    const { frameworks } = await askQuestions({
-        type: assumeYes || !reviewScannedFields ? null : 'multiselect',
-        name: 'frameworks',
-        message: 'Frameworks (Space to select, Enter to confirm):',
-        choices: FRAMEWORK_CHOICES.map(f => ({ title: f, value: f, selected: (scanned?.frameworks || []).includes(f) })),
-        min: 0
-    });
-
-    const dbAndInfra = await askQuestions([
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'database', message: 'Database / ORM:',
-            choices: DATABASE_CHOICES.map(d => ({ title: d, value: d })),
-            initial: Math.max(DATABASE_CHOICES.indexOf(scanned?.database || 'none'), 0)
-        },
-        { type: assumeYes || !reviewScannedFields ? null : 'confirm', name: 'uses_docker', message: 'Uses Docker / Docker Compose?', initial: scanned?.uses_docker ?? true },
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'cloud', message: 'Cloud Provider:',
-            choices: CLOUD_CHOICES.map(c => ({ title: c, value: c })),
-            initial: Math.max(CLOUD_CHOICES.indexOf(scanned?.cloud || 'none'), 0)
-        }
-    ]);
-
-    const { package_manager, test_framework, max_file_lines } = await askQuestions([
-        {
-            type: assumeYes || !reviewScannedFields ? null : 'select', name: 'package_manager', message: 'Package Manager:',
-            choices: PACKAGE_MANAGER_CHOICES.map(p => ({ title: p, value: p })),
-            initial: Math.max(PACKAGE_MANAGER_CHOICES.indexOf(scanned?.package_manager || 'auto-detect'), 0)
-        },
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'test_framework', message: 'Test Framework (jest, phpunit, etc):', initial: scanned?.test_framework || 'auto-detect' },
-        { type: assumeYes || !reviewScannedFields ? null : 'text', name: 'max_file_lines', message: 'Max lines per file:', initial: scanned?.max_file_lines || '300' }
-    ]);
-
-    // Combine data
-    const data = {
-        project_name: project_name || scanned?.project_name || path.basename(targetDir),
-        description: description || scanned?.description || 'A software project',
-        project_type: project_type || scanned?.project_type || 'web-app',
-        primary_language: primary_language || scanned?.primary_language || 'typescript',
-        frameworks: frameworks || scanned?.frameworks || [],
-        ...dbAndInfra, package_manager, test_framework, max_file_lines
-    };
+    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);
@@ -1307,40 +1585,58 @@ async function main() {
     data.scan_evidence = scanned?.scan_evidence || [];
     data.app_root = scanned?.app_root || '.';
 
-    data.infrastructure = [];
-    if (data.uses_docker) data.infrastructure.push('docker');
-    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
-
-    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
-
-    // Shared entry files are written after the .agent folder is available.
+    data.infrastructure = [];
+    if (data.uses_docker) data.infrastructure.push('docker');
+    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
 
-    // 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 shouldSetupMcp = !skipMcpSetup;
+
+    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
 
+    // Shared entry files are written after the .agent folder is available.
 
-    const generatedFiles = [
+    // 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('.agents/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()],
         [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
-        [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
-        [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc(data)],
-        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()]
-    ];
-
-    for (const [relativePath, content] of generatedFiles) {
-        const wrote = await writeGeneratedFile(relativePath, content, assumeYes);
-        if (wrote) console.log(`  ${pc.green('OK')} Generated ${pc.bold(relativePath)}`);
-        else console.log(`  ${pc.yellow('~')} Skipped ${pc.bold(relativePath)}`);
-    }
-
-    console.log(`\n${pc.bold(pc.green('Done!'))}
+        [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'}
@@ -1348,25 +1644,35 @@ async function main() {
   ${pc.bold('Generated:')}
     - ${pc.bold('AGENTS.md')} shared entry for Codex, Antigravity, and Claude Code
     - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
-    - ${pc.bold('GEMINI.md')} Antigravity entry
-    - ${pc.bold('.agent/docs/')} scan-based project rules
-    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
-
+    - ${pc.bold('GEMINI.md')} Antigravity entry
+    - ${pc.bold('.agent/docs/')} scan-based project rules
+    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
+    - ${pc.bold('.agents/skills/')} selected Codex native skills
+    - ${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. Review ${pc.bold('.agent/docs/')} and replace any TODO: refine items with real project facts
+    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')}, and ${pc.bold('.agent/')}
     3. Open the project in Codex, Antigravity, or Claude Code
 
   ${pc.bold('Copy this prompt into your AI editor:')}
 ${pc.dim('---')}
 Read AGENTS.md and all files under .agent/docs/.
-Scan this repository.
-Update .agent/docs/project.md, .agent/docs/architecture.md, and .agent/docs/conventions.md with factual project-specific rules.
+Ask me what this project does and any important conventions I want preserved.
+Then scan this repository.
+Update AGENTS.md 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);