@shanyucoder/flowgrid 0.1.4 → 0.1.8

package/bin/flowgrid.mjs

@@ -19,7 +19,21 @@ import {
   applyDocsHubScaffold,
   applyTestsHubScaffold,
   promptHubRoot,
+  hubPathUnderProject,
 } from './lib/init-scaffold.mjs';
+import { promptFeAdapter, promptBeAdapter } from './lib/init-adapters.mjs';
+import {
+  loadStackPresetJson,
+  mergeStackIntoFlowgridConfig,
+  resolveStackPresetKey,
+} from './lib/merge-stack-config.mjs';
+import { defaultE2eRootRel, DEFAULT_E2E_ROOT_REL } from '../engines/shared/flowgrid-e2e-root.mjs';
+import {
+  resolveFlowgridContext,
+  flowgridContextToEnv,
+  ENV_DOCS_ROOT,
+} from '../engines/shared/resolve-flowgrid-context.mjs';
+import { injectFlowgridConsumerScripts } from './lib/inject-consumer-scripts.mjs';
 
 function packageRootFromMeta(metaUrl) {
   return path.resolve(path.dirname(fileURLToPath(metaUrl)), '..');
@@ -35,6 +49,27 @@ function assertNodeVersion() {
   }
 }
 
+function printDefaultHelp() {
+  const lines = [
+    'FlowGrid CLI — chạy trong thư mục repo đích (cd project trước khi init).',
+    '',
+    'Cài một lần (global):',
+    '  npm install -g @shanyucoder/flowgrid',
+    '  pnpm add -g @shanyucoder/flowgrid',
+    '',
+    'Khởi tạo repo đích:',
+    '  flowgrid init',
+    '',
+    'Khác:',
+    '  flowgrid doctor · flowgrid update · flowgrid harness sync · flowgrid audit',
+    '',
+    'npx (không cài global) — phải gọi bin flowgrid:',
+    '  npx -p @shanyucoder/flowgrid flowgrid init',
+    '  (không dùng: npx @shanyucoder/flowgrid — sẽ không truyền lệnh init)',
+  ];
+  console.log(lines.join('\n'));
+}
+
 export async function main() {
   assertNodeVersion();
   const args = process.argv.slice(2);
@@ -46,6 +81,23 @@ export async function main() {
   }
 
   const command = args[0];
+
+  if (command === 'api:check') {
+    try {
+      const { checkBackendSpecFiles, parseApiCheckArgs } = await import(
+        '../engines/openapi/check-backend-spec.mjs'
+      );
+      const ctx = resolveFlowgridContext({ argv: args.slice(1) });
+      const checkArgv = parseApiCheckArgs(ctx.argv);
+      const cwd = ctx.docsRoot ?? ctx.projectRoot;
+      await checkBackendSpecFiles(checkArgv, cwd);
+      process.exit(0);
+    } catch (e) {
+      console.error(pc.red(e.message ?? String(e)));
+      process.exit(1);
+    }
+  }
+
   const engineCommands = ['split', 'merge', 'check', 'split_all', 'normalize', 'render', 'publish', 'legacy_validate', 'extract_i18n', 'openapi_render', 'openapi_build_ui', 'openapi_gen'];
   
   if (engineCommands.includes(command)) {
@@ -65,11 +117,14 @@ export async function main() {
   if (testCommands.includes(command)) {
     try {
       const { runEngine } = await import('../dist/test/engines/run.js');
-      const { extractTestsDocsFlag, ENV_TESTS_DOC } = await import('../engines/shared/flowgrid-tests-docs.mjs');
-      const root = process.cwd();
+      const { flowgridContextToEnv, resolveFlowgridContext } = await import(
+        '../engines/shared/resolve-flowgrid-context.mjs'
+      );
+      const ctx = resolveFlowgridContext({ argv: args.slice(1) });
+      const root = ctx.projectRoot;
       let engineRel = [];
-      const { argv, testsDocs } = extractTestsDocsFlag(args.slice(1));
-      const engineEnv = testsDocs ? { [ENV_TESTS_DOC]: testsDocs } : {};
+      const argv = ctx.argv;
+      const engineEnv = flowgridContextToEnv(ctx);
       
       if (command === 'cases:render') engineRel = ['cases', 'render-cases.mjs'];
       if (command === 'cases:check') engineRel = ['cases', 'check-plans.mjs'];
@@ -97,6 +152,17 @@ export async function main() {
     }
   }
 
+  if (command === 'registry:sync') {
+    try {
+      const { runRegistrySync } = await import('../engines/registry-sync/run-registry-sync.mjs');
+      const res = await runRegistrySync(args.slice(1));
+      process.exit(res.code ?? 0);
+    } catch (e) {
+      console.error(pc.red('registry:sync failed: ' + (e.message ?? String(e))));
+      process.exit(1);
+    }
+  }
+
   const codegenCommands = [
     'api-gen', 'api-gen:dry', 'api-registry', 'api-unit-gen', 'api-unit-gen:dry', 'api-unit-registry',
     'gen', 'gen:dry', 'registry', 'unit-gen', 'unit-gen:dry', 'unit-registry',
@@ -106,18 +172,19 @@ export async function main() {
   
   if (codegenCommands.includes(command)) {
     try {
-      const configPath = path.join(process.cwd(), '.flowgrid', 'config.json');
-      let config = {};
-      if (fs.existsSync(configPath)) {
-        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-      }
       const root = process.cwd();
-      const argv = args.slice(1);
+      const ctx = resolveFlowgridContext({ cwd: root, argv: args.slice(1) });
+      const config = ctx.config ?? {};
+      const argv = ctx.argv;
       const isDry = command.endsWith(':dry');
+      const docsRoot = ctx.docsRoot;
+      if (docsRoot && !process.env[ENV_DOCS_ROOT]) {
+        process.env[ENV_DOCS_ROOT] = docsRoot;
+      }
+      Object.assign(process.env, flowgridContextToEnv(ctx, {}));
       
       const beAdapter = config.backend?.adapter || 'fastapi';
       const feAdapter = config.frontend?.adapter || 'nextjs';
-      const docsRoot = config.frontend?.docsRoot;
 
       if (command.startsWith('api-')) {
         const { runBeEngine } = await import('../dist/codegen/adapters/run-be.js');
@@ -175,22 +242,19 @@ export async function main() {
 
   if (command === 'dev' || command === 'serve') {
     const { spawn, spawnSync } = await import('node:child_process');
-    const configPath = path.join(process.cwd(), '.flowgrid', 'config.json');
-    let docsRoot, testsRoot, feAdapter;
-    if (fs.existsSync(configPath)) {
-      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-      docsRoot = config.frontend?.docsRoot || config.backend?.docsRoot;
-      testsRoot = config.frontend?.testsRoot ?? config.backend?.testsRoot;
-      feAdapter = config.frontend?.adapter;
-    }
+    const ctx = resolveFlowgridContext({ argv: args.slice(1) });
+    const config = ctx.config ?? {};
+    const docsRoot = ctx.docsRoot;
+    const testsRoot = ctx.testsDocs;
+    let feAdapter = config.frontend?.adapter;
     feAdapter = feAdapter || 'nextjs';
-    const projectRoot = process.cwd();
+    const projectRoot = ctx.projectRoot;
 
     // ── gen-common: initial build (watch is handled by VitePress plugin) ──
     const webAdapters = new Set(['nuxt4', 'nextjs']);
     if (docsRoot && webAdapters.has(feAdapter)) {
       const resolvedDocsRoot = path.resolve(docsRoot);
-      const packageRoot = path.resolve(new URL(import.meta.url).pathname, '../..');
+      const packageRoot = packageRootFromMeta(import.meta.url);
       const commonEngine = path.join(packageRoot, 'adapters', 'shared', 'common-gen.mjs');
       const env = {
         ...process.env,
@@ -215,14 +279,14 @@ export async function main() {
     // ── VitePress dev servers ────────────────────────────────────────
     if (docsRoot) {
       console.log(pc.blue(`[Docs] Starting VitePress in ${docsRoot}...`));
-      spawn('npx', ['vitepress', 'dev', docsRoot, ...args.slice(1)], { stdio: 'inherit' });
+      spawn('npx', ['vitepress', 'dev', docsRoot, ...ctx.argv], { stdio: 'inherit' });
     }
     if (testsRoot) {
       console.log(pc.blue(`[Tests] Starting VitePress in ${testsRoot} (Port 5174)...`));
-      spawn('npx', ['vitepress', 'dev', testsRoot, '--port', '5174', ...args.slice(1)], { stdio: 'inherit' });
+      spawn('npx', ['vitepress', 'dev', testsRoot, '--port', '5174', ...ctx.argv], { stdio: 'inherit' });
     }
     if (!docsRoot && !testsRoot) {
-      spawn('npx', ['vitepress', 'dev', ...args.slice(1)], { stdio: 'inherit' });
+      spawn('npx', ['vitepress', 'dev', ...ctx.argv], { stdio: 'inherit' });
     }
     // Keep alive for spawned processes
     setInterval(() => {}, 1000);
@@ -231,27 +295,97 @@ export async function main() {
 
   if (command === 'build') {
     const { spawnSync } = await import('node:child_process');
-    const configPath = path.join(process.cwd(), '.flowgrid', 'config.json');
-    let docsRoot, testsRoot;
-    if (fs.existsSync(configPath)) {
-      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-      docsRoot = config.frontend?.docsRoot || config.backend?.docsRoot;
-      testsRoot = config.frontend?.testsRoot ?? config.backend?.testsRoot;
-    }
+    const ctx = resolveFlowgridContext({ argv: args.slice(1) });
+    const docsRoot = ctx.docsRoot;
+    const testsRoot = ctx.testsDocs;
     if (docsRoot) {
       console.log(pc.blue(`[Docs] Building VitePress in ${docsRoot}...`));
-      spawnSync('npx', ['vitepress', 'build', docsRoot, ...args.slice(1)], { stdio: 'inherit' });
+      spawnSync('npx', ['vitepress', 'build', docsRoot, ...ctx.argv], { stdio: 'inherit' });
     }
     if (testsRoot) {
       console.log(pc.blue(`[Tests] Building VitePress in ${testsRoot}...`));
-      spawnSync('npx', ['vitepress', 'build', testsRoot, ...args.slice(1)], { stdio: 'inherit' });
+      spawnSync('npx', ['vitepress', 'build', testsRoot, ...ctx.argv], { stdio: 'inherit' });
     }
     if (!docsRoot && !testsRoot) {
-      spawnSync('npx', ['vitepress', 'build', ...args.slice(1)], { stdio: 'inherit' });
+      spawnSync('npx', ['vitepress', 'build', ...ctx.argv], { stdio: 'inherit' });
     }
     return;
   }
 
+  if (command === 'repo-maps') {
+    const sub = args[1] || 'check';
+    const {
+      compareConfigAndRepoMaps,
+      writeRepoMapsFromConfig,
+      writeConfigFromRepoMaps,
+    } = await import('./lib/repo-maps-align.mjs');
+    const projectRoot = process.cwd();
+    const cmp = compareConfigAndRepoMaps(projectRoot);
+
+    if (sub === 'check') {
+      if (cmp.conflicts.length) {
+        for (const c of cmp.conflicts) {
+          console.log(pc.yellow(`conflict ${c.key}: config=${c.configPath} map=${c.mapPath}`));
+        }
+      }
+      if (cmp.missingInMap.length) {
+        console.log(pc.gray(`missing in ${'platform-repos.local.json'}: ${cmp.missingInMap.join(', ')}`));
+      }
+      if (!cmp.conflicts.length && !cmp.missingInMap.length) {
+        console.log(pc.green('repo-maps: aligned with .flowgrid/config.json'));
+      } else {
+        console.log(pc.cyan('Fix: flowgrid repo-maps align  (or repo-maps sync --from-config)'));
+      }
+      process.exit(cmp.conflicts.length ? 1 : 0);
+    }
+
+    if (sub === 'sync') {
+      const from = args.includes('--from-map') ? 'map' : 'config';
+      if (from === 'config') {
+        const { file } = writeRepoMapsFromConfig(projectRoot);
+        console.log(pc.green(`Updated ${path.relative(projectRoot, file)} from config`));
+      } else {
+        writeConfigFromRepoMaps(projectRoot);
+        console.log(pc.green('Updated .flowgrid/config.json from platform-repos.local.json'));
+      }
+      process.exit(0);
+    }
+
+    if (sub === 'align') {
+      if (!cmp.conflicts.length) {
+        if (cmp.missingInMap.length) {
+          const { file } = writeRepoMapsFromConfig(projectRoot);
+          console.log(pc.green(`Seeded ${path.relative(projectRoot, file)} from init config`));
+        } else {
+          console.log(pc.green('Already aligned — nothing to do'));
+        }
+        process.exit(0);
+      }
+      const { applyAlignChoices } = await import('./lib/repo-maps-align.mjs');
+      const choices = {};
+      for (const c of cmp.conflicts) {
+        const choice = await select({
+          message: `Chốt path cho hub "${c.key}" (config lúc init vs platform-repos.local):`,
+          options: [
+            { value: 'config', label: `Giữ config → ${c.configPath}` },
+            { value: 'map', label: `Giữ repo map → ${c.mapPath}` },
+          ],
+        });
+        if (isCancel(choice)) {
+          cancel('Cancelled.');
+          process.exit(0);
+        }
+        choices[c.key] = choice;
+      }
+      applyAlignChoices(projectRoot, choices);
+      console.log(pc.green('Aligned config + platform-repos.local.json — run flowgrid harness sync if MCP paths changed'));
+      process.exit(0);
+    }
+
+    console.log('Usage: flowgrid repo-maps check | align | sync [--from-config|--from-map]');
+    process.exit(1);
+  }
+
   if (command === 'update') {
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
     const { runCliUpdate } = await import('./lib/cli-update.mjs');
@@ -310,7 +444,18 @@ export async function main() {
     }
 
     if (!keepAgents) {
-      const dirs = ['.agents', '.gemini', '.cursor', '.claude', '.codex', '.opencode', '.hermes', '.kiro', '.kilo'];
+      const dirs = [
+        '.agents',
+        '.antigravity',
+        '.gemini',
+        '.cursor',
+        '.claude',
+        '.codex',
+        '.opencode',
+        '.hermes',
+        '.kiro',
+        '.kilo',
+      ];
       for (const d of dirs) {
         const p = path.join(process.cwd(), d);
         if (fs.existsSync(p)) {
@@ -368,7 +513,7 @@ export async function main() {
 
   if (command === 'doctor') {
     try {
-      const packageRoot = path.resolve(new URL(import.meta.url).pathname, '../../');
+      const packageRoot = packageRootFromMeta(import.meta.url);
       const fix = args.includes('--fix');
       const report = runDoctor({
         projectRoot: process.cwd(),
@@ -385,7 +530,7 @@ export async function main() {
 
   if (command === 'harness' && args[1] === 'sync') {
     try {
-      const packageRoot = path.resolve(new URL(import.meta.url).pathname, '../../');
+      const packageRoot = packageRootFromMeta(import.meta.url);
       runHarnessSync(args.slice(2), { packageRoot });
       process.exit(0);
     } catch (e) {
@@ -404,7 +549,12 @@ export async function main() {
     process.exit(1);
   }
 
-  if (command && command !== 'init') {
+  if (!command) {
+    printDefaultHelp();
+    return;
+  }
+
+  if (command !== 'init') {
     console.error(pc.red(`Lệnh không hợp lệ: ${command}`));
     console.log(`Chạy 'flowgrid init', 'flowgrid doctor', 'flowgrid update', 'flowgrid harness sync', hoặc 'flowgrid audit'.`);
     process.exit(1);
@@ -417,7 +567,8 @@ export async function main() {
   const agentsAns = await multiselect({
     message: 'Select Agents/Skills to integrate:',
     options: [
-      { value: 'gemini_antigravity', label: 'Gemini & Antigravity' },
+      { value: 'gemini', label: 'Gemini (CLI / VS Code extension) → .agents/' },
+      { value: 'antigravity', label: 'Google Antigravity IDE → .antigravity/' },
       { value: 'cursor', label: 'Cursor' },
       { value: 'claude', label: 'Claude Code' },
       { value: 'codex', label: 'Codex CLI' },
@@ -433,6 +584,19 @@ export async function main() {
     process.exit(0);
   }
   const selectedAgents = agentsAns;
+  if (selectedAgents.includes('gemini')) {
+    console.log(pc.gray('Gemini: harness → .agents/ (mcp.json + .agents/skills/).\n'));
+  }
+  if (selectedAgents.includes('antigravity')) {
+    console.log(
+      pc.gray(
+        'Antigravity IDE: harness → .antigravity/ (mcp_config.json + .antigravity/skills/) — không dùng .agents/.\n',
+      ),
+    );
+  }
+  if (selectedAgents.length === 0) {
+    console.log(pc.yellow('Không chọn agent — bỏ qua sync harness/MCP (chỉ .flowgrid + scaffold).\n'));
+  }
 
   // 2. Project Type
   const selectedType = await select({
@@ -459,6 +623,7 @@ export async function main() {
   let testsHubInRepo = false;
   let scaffoldDocs = false;
   let scaffoldTests = false;
+  let feE2eRoot = '';
   const projectRoot = process.cwd();
   let baseProfile = 'standard';
   let goldenSample = '';
@@ -495,22 +660,12 @@ export async function main() {
       });
       if (isCancel(feAns)) { cancel('Cancelled.'); process.exit(0); }
       feAdapter = feAns;
-      beAdapter = 'nestjs';
+      beAdapter = await promptBeAdapter({ select, text, isCancel, cancel });
       console.log(pc.cyan(`=> Selected Fullstack: Frontend (${feAdapter}) + Backend (${beAdapter})`));
     } else if (selectedType === 'Frontend') {
-      const feAns = await text({
-        message: 'Enter Frontend technology (e.g. nuxt4, nextjs, or custom):',
-        placeholder: baseProfile === 'custom' ? 'custom' : 'nuxt4'
-      });
-      if (isCancel(feAns)) { cancel('Cancelled.'); process.exit(0); }
-      feAdapter = feAns || (baseProfile === 'custom' ? 'custom' : 'nuxt4');
+      feAdapter = await promptFeAdapter({ select, text, isCancel, cancel });
     } else if (selectedType === 'Backend') {
-      const beAns = await text({
-        message: 'Enter Backend technology (e.g. nestjs, fastapi, laravel, dotnet, or custom):',
-        placeholder: baseProfile === 'custom' ? 'custom' : 'nestjs'
-      });
-      if (isCancel(beAns)) { cancel('Cancelled.'); process.exit(0); }
-      beAdapter = beAns || (baseProfile === 'custom' ? 'custom' : 'nestjs');
+      beAdapter = await promptBeAdapter({ select, text, isCancel, cancel });
     }
 
     const needsDocsHub =
@@ -558,6 +713,34 @@ export async function main() {
       scaffoldTests = testsHub.scaffold;
     }
 
+    const needsE2eRoot =
+      selectedType === 'Frontend' ||
+      selectedType === 'Fullstack' ||
+      (selectedType === 'Backend' && feTestRoot);
+    if (needsE2eRoot) {
+      const e2eDefault = defaultE2eRootRel(selectedType);
+      const e2eAns = await text({
+        message:
+          selectedType === 'Backend'
+            ? 'Automation root (Playwright api-e2e / request specs; tùy chọn Newman; khác tests-docs YAML):'
+            : 'Playwright e2e-root (chứa *.spec.ts / Page Object; khác tests-docs hub YAML):',
+        defaultValue: e2eDefault,
+        placeholder: e2eDefault,
+      });
+      if (isCancel(e2eAns)) {
+        cancel('Cancelled.');
+        process.exit(0);
+      }
+      feE2eRoot = (e2eAns || e2eDefault).trim() || e2eDefault;
+      console.log(
+        pc.gray(
+          selectedType === 'Backend'
+            ? `  (tests-docs = TC-*.yaml; automation = tests/api-e2e + audit e2e — mặc định BE: ${e2eDefault})`
+            : `  (tests-docs = kế hoạch TC-*.yaml; e2e-root = code Playwright — mặc định ${e2eDefault})`,
+        ),
+      );
+    }
+
     if (selectedType === 'Test') {
       feTestRoot = '.';
       testsHubInRepo = true;
@@ -613,6 +796,13 @@ export async function main() {
     if (beAdapter) {
       console.log(`- Backend Adapter: ${beAdapter}`);
     }
+    if (feE2eRoot) {
+      const e2eLabel =
+        selectedType === 'Backend'
+          ? 'Automation root (Playwright api-e2e / Newman)'
+          : 'Playwright e2e-root';
+      console.log(`- ${e2eLabel}: ${feE2eRoot} (testcase:gen / testcase:gen:api / audit e2e)`);
+    }
   }
   console.log(`- Setup Agents: ${selectedAgents.length > 0 ? selectedAgents.join(', ') : 'No'}`);
   console.log(`- Destination folder: .flowgrid/`);
@@ -632,6 +822,8 @@ export async function main() {
     fs.mkdirSync(targetDir, { recursive: true });
   }
 
+  const packageRoot = packageRootFromMeta(import.meta.url);
+
   const projectConfig = {
     type: selectedType,
     agents: selectedAgents,
@@ -643,6 +835,7 @@ export async function main() {
       adapter: feAdapter,
       docsRoot: feDocRoot || undefined,
       testsRoot: feTestRoot || undefined,
+      e2eRoot: feE2eRoot || defaultE2eRootRel(selectedType),
       docsHubInRepo: feDocRoot ? docsHubInRepo : undefined,
       testsHubInRepo: feTestRoot ? testsHubInRepo : undefined,
     } : null,
@@ -650,21 +843,50 @@ export async function main() {
       adapter: beAdapter,
       docsRoot: (!feAdapter && feDocRoot) ? feDocRoot : undefined,
       testsRoot: (!feAdapter && feTestRoot) ? feTestRoot : undefined,
+      e2eRoot: (!feAdapter && feTestRoot)
+        ? (feE2eRoot || defaultE2eRootRel('Backend'))
+        : undefined,
       docsHubInRepo: (!feAdapter && feDocRoot) ? docsHubInRepo : undefined,
       testsHubInRepo: (!feAdapter && feTestRoot) ? testsHubInRepo : undefined,
     } : null
   };
+
+  const stackKey = resolveStackPresetKey({
+    type: selectedType,
+    feAdapter,
+    beAdapter,
+  });
+  const stackPreset = loadStackPresetJson(packageRoot, stackKey);
+  mergeStackIntoFlowgridConfig(projectConfig, stackPreset, process.cwd());
+  if (stackPreset?.stack) {
+    console.log(pc.gray(`  + Stack preset: ${stackKey} (registries/commands for ArtifactGraph MCP)`));
+  }
+
   fs.writeFileSync(path.join(targetDir, 'config.json'), JSON.stringify(projectConfig, null, 2));
   console.log("  + Wrote config.json");
 
-  const packageRoot = path.resolve(new URL(import.meta.url).pathname, '../../');
-  
+  if (feDocRoot || feTestRoot || selectedType === 'Document' || selectedType === 'Test') {
+    try {
+      const { writeRepoMapsFromConfig } = await import('./lib/repo-maps-align.mjs');
+      writeRepoMapsFromConfig(process.cwd());
+      console.log(pc.gray('  + Seeded platform-repos.local.json from hub pointers (config SSOT)'));
+    } catch {
+      /* non-fatal */
+    }
+  }
+
   const copyRecursive = (srcDir, destDir, log = false) => {
     if (!fs.existsSync(srcDir)) return;
     if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
     const items = fs.readdirSync(srcDir, { withFileTypes: true });
     for (const item of items) {
-      if (['node_modules', '.git', 'dist', '.agents', '.gemini', '.cursor', '.flowgrid'].includes(item.name)) continue;
+      if (
+        ['node_modules', '.git', 'dist', '.agents', '.antigravity', '.gemini', '.cursor', '.flowgrid'].includes(
+          item.name,
+        )
+      ) {
+        continue;
+      }
       if (item.name.endsWith('.db')) continue;
 
       const srcPath = path.join(srcDir, item.name);
@@ -723,6 +945,23 @@ export async function main() {
     });
   }
 
+  if (feE2eRoot && hubPathUnderProject(process.cwd(), feE2eRoot)) {
+    const e2eAbs = path.join(process.cwd(), feE2eRoot);
+    if (!fs.existsSync(e2eAbs)) {
+      fs.mkdirSync(e2eAbs, { recursive: true });
+      fs.writeFileSync(path.join(e2eAbs, '.gitkeep'), '');
+      console.log(pc.blue(`  + Automation / e2e-root scaffold → ${feE2eRoot}/`));
+    }
+    if (selectedType === 'Backend' && testsHubInRepo) {
+      const apiE2eAbs = path.join(process.cwd(), 'tests', 'api-e2e');
+      if (!fs.existsSync(apiE2eAbs)) {
+        fs.mkdirSync(apiE2eAbs, { recursive: true });
+        fs.writeFileSync(path.join(apiE2eAbs, '.gitkeep'), '');
+        console.log(pc.blue(`  + API hook specs scaffold → tests/api-e2e/`));
+      }
+    }
+  }
+
   console.log(pc.blue(`[INFO] Syncing global templates & schemas...`));
   const tplSrc = path.join(packageRoot, 'templates');
   const tplDest = path.join(targetDir, 'templates');
@@ -753,6 +992,19 @@ export async function main() {
       console.log(
         pc.gray(`  + Wrote MCP config: ${path.relative(process.cwd(), mcpConfigPath) || mcpConfigPath}`)
       );
+      const skillsDir = path.join(agentDir, 'skills');
+      const skillCount = fs.existsSync(skillsDir)
+        ? fs.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length
+        : 0;
+      const relAgent = path.relative(process.cwd(), agentDir) || profile.dirName;
+      console.log(pc.gray(`  + Skills: ${relAgent}/skills/ (${skillCount} skill folders)`));
+      if (skillCount === 0) {
+        console.log(
+          pc.yellow(
+            `  ! Không có skill — thử: flowgrid harness sync --agent=${agent}`,
+          ),
+        );
+      }
     }
     writeRootAgentsMd(process.cwd(), selectedAgents);
     console.log(pc.gray('  + Wrote root AGENTS.md'));
@@ -777,63 +1029,14 @@ export async function main() {
         pkg.devDependencies['@braintree/sanitize-url'] = '^7.1.0';
       }
 
-      pkg.scripts['flowgrid:audit'] = 'flowgrid audit';
-      pkg.scripts['flowgrid:audit:spec'] = 'flowgrid audit spec';
-      pkg.scripts['flowgrid:audit:flow'] = 'flowgrid audit flow';
-      pkg.scripts['flowgrid:audit:api'] = 'flowgrid audit api';
-      pkg.scripts['flowgrid:audit:testcase'] = 'flowgrid audit testcase';
-      pkg.scripts['flowgrid:audit:fe-be'] = 'flowgrid audit fe-be';
-      pkg.scripts['flowgrid:audit:scenario'] = 'flowgrid audit scenario';
-      pkg.scripts['flowgrid:audit:e2e'] = 'flowgrid audit e2e';
-      pkg.scripts['flowgrid:audit:legacy'] = 'flowgrid audit legacy';
-      pkg.scripts['flowgrid:harness-sync'] = 'flowgrid harness sync';
-      pkg.scripts['flowgrid:harness-sync:full-docs'] = 'flowgrid harness sync --full-docs';
-      pkg.scripts['flowgrid:doctor'] = 'flowgrid doctor';
-      pkg.scripts['flowgrid:doctor:fix'] = 'flowgrid doctor --fix';
-
-      const injectDocsHubScripts =
-        selectedType === 'Document' || (feDocRoot && docsHubInRepo);
-      if (injectDocsHubScripts) {
-        pkg.scripts['flowgrid:split'] = 'flowgrid split';
-        pkg.scripts['flowgrid:split_all'] = 'flowgrid split_all';
-        pkg.scripts['flowgrid:render'] = 'flowgrid render';
-        pkg.scripts['flowgrid:openapi'] = 'flowgrid openapi_render';
-        pkg.scripts['flowgrid:openapi-ui'] = 'flowgrid openapi_build_ui';
-        pkg.scripts['flowgrid:dev'] = 'flowgrid dev';
-        pkg.scripts['flowgrid:build'] = 'flowgrid build';
-        pkg.scripts['flowgrid:publish'] = 'flowgrid publish';
-        pkg.scripts['flow:dev'] = 'flowgrid dev';
-        pkg.scripts['flow:render'] = 'flowgrid render';
-        pkg.scripts['flow:publish'] = 'flowgrid publish';
-      }
-
-      if (selectedType === 'Frontend' || selectedType === 'Fullstack') {
-        pkg.scripts['flowgrid:gen'] = 'flowgrid gen';
-        pkg.scripts['flowgrid:unit'] = 'flowgrid unit-gen';
-        pkg.scripts['flowgrid:css'] = 'flowgrid gen-css';
-      }
-
-      if (selectedType === 'Backend' || selectedType === 'Fullstack') {
-        pkg.scripts['flowgrid:api-gen'] = 'flowgrid api-gen';
-        pkg.scripts['flowgrid:api-unit'] = 'flowgrid api-unit-gen';
-        pkg.scripts['flowgrid:openapi'] = 'flowgrid openapi_render';
-      }
-
-      if (selectedType === 'Frontend' || selectedType === 'Backend' || selectedType === 'Fullstack') {
-        pkg.scripts['flowgrid:contract'] = 'flowgrid contract-gen';
-      }
+      injectFlowgridConsumerScripts(pkg, {
+        selectedType,
+        feDocRoot,
+        feTestRoot,
+        docsHubInRepo,
+        testsHubInRepo,
+      });
 
-      const injectTestsHubScripts = selectedType === 'Test' || Boolean(feTestRoot);
-      if (injectTestsHubScripts) {
-        pkg.scripts['flowgrid:cases'] = 'flowgrid cases:render';
-        pkg.scripts['flowgrid:cases-check'] = 'flowgrid cases:check';
-        pkg.scripts['flowgrid:cases-cov'] = 'flowgrid cases:coverage';
-        pkg.scripts['flowgrid:cases-gate'] = 'flowgrid cases:gate';
-        pkg.scripts['flowgrid:e2e-gen'] = 'flowgrid testcase:gen';
-        pkg.scripts['flowgrid:api-e2e-gen'] = 'flowgrid testcase:gen:api';
-        pkg.scripts['flowgrid:e2e-reg'] = 'flowgrid e2e-registry';
-      }
-      
       fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
       console.log(pc.blue('  + Injected flowgrid:* & flow:* scripts into package.json'));
     } catch (e) {
@@ -862,6 +1065,20 @@ export async function main() {
     console.log(pc.yellow('  ! Không thể khởi tạo SQLite cache (chưa có specs/registry): ' + e.message));
   }
 
+  if (['Frontend', 'Backend', 'Fullstack'].includes(selectedType)) {
+    try {
+      const { runRegistrySync } = await import('../engines/registry-sync/run-registry-sync.mjs');
+      console.log(pc.blue('\n[INFO] Quét base → DSL registry (registry:sync)...'));
+      await runRegistrySync([], {
+        projectRoot: process.cwd(),
+        packageRoot: packageRootFromMeta(import.meta.url),
+        config: projectConfig,
+      });
+    } catch (e) {
+      console.log(pc.yellow('  ! registry:sync skipped: ' + e.message));
+    }
+  }
+
   const dslBackupDir = path.join(process.cwd(), 'artifactgraph');
   if (!fs.existsSync(dslBackupDir)) {
     fs.mkdirSync(dslBackupDir, { recursive: true });
@@ -884,7 +1101,10 @@ export async function main() {
     const optionalAns = await multiselect({
       message: 'Optional toolkits to initialize now (none = skip, add later):',
       options: [
-        { value: 'codegraph', label: 'Codegraph — semantic code intelligence' }
+        {
+          value: 'codegraph',
+          label: 'Codegraph — semantic code intelligence (cần CLI `codegraph` đã cài)',
+        },
       ],
       required: false
     });
@@ -892,11 +1112,28 @@ export async function main() {
       console.log(pc.blue('\n[INFO] Initializing Codegraph...'));
       try {
         const { spawnSync } = await import('node:child_process');
-        const res = spawnSync('npx', ['codegraph', 'init'], { stdio: 'inherit' });
-        if (res.status === 0) {
-          console.log('  + Codegraph initialized successfully');
+        const shell = process.platform === 'win32';
+        const where = process.platform === 'win32' ? 'where' : 'which';
+        const hasCodegraph =
+          spawnSync(where, ['codegraph'], { encoding: 'utf8', shell }).status === 0;
+        if (!hasCodegraph) {
+          console.log(
+            pc.yellow(
+              '  ! CodeGraph CLI chưa có trên PATH — bỏ qua (init FlowGrid vẫn hoàn tất).',
+            ),
+          );
+          console.log(
+            pc.gray(
+              '  Sau này: cài CodeGraph theo tài liệu team → trong repo này chạy `codegraph init` → MCP: `platform-dna codegraph:wire` (skill /configure-repo-maps).',
+            ),
+          );
         } else {
-          console.log(pc.yellow(`  ! Codegraph initialization failed with status ${res.status}`));
+          const res = spawnSync('codegraph', ['init'], { stdio: 'inherit', shell });
+          if (res.status === 0) {
+            console.log('  + Codegraph initialized successfully');
+          } else {
+            console.log(pc.yellow(`  ! Codegraph init failed (status ${res.status})`));
+          }
         }
       } catch (e) {
         console.log(pc.yellow('  ! Failed to run Codegraph init: ' + e.message));