@xelth/eck-snapshot 5.9.0 → 6.4.0

package/src/cli/commands/createSnapshot.js

@@ -17,14 +17,16 @@ import {
   ensureSnapshotsInGitignore, initializeEckManifest, generateTimestamp,
   getShortRepoName, SecretScanner
 } from '../../utils/fileUtils.js';
-import { detectProjectType, getProjectSpecificFiltering } from '../../utils/projectDetector.js';
+import { detectProjectType, getProjectSpecificFiltering, getAllDetectedTypes } from '../../utils/projectDetector.js';
 import { estimateTokensWithPolynomial, generateTrainingCommand } from '../../utils/tokenEstimator.js';
 import { loadSetupConfig, getProfile } from '../../config.js';
 import { applyProfileFilter } from '../../utils/fileUtils.js';
 import { saveGitAnchor } from '../../utils/gitUtils.js';
 import { skeletonize } from '../../core/skeletonizer.js';
+import { getDepthConfig } from '../../core/depthConfig.js';
 import { updateClaudeMd } from '../../utils/claudeMdGenerator.js';
 import { generateOpenCodeAgents } from '../../utils/opencodeAgentsGenerator.js';
+import { ensureProjectMcpConfig, ensureProjectOpenCodeConfig, ensureProjectCodexConfig } from './setupMcp.js';
 
 /**
  * Creates dynamic project context based on detection results
@@ -254,14 +256,14 @@ async function getGitCommitHash(projectPath) {
   return null;
 }
 
-async function estimateProjectTokens(projectPath, config, projectType = null) {
+async function estimateProjectTokens(projectPath, config, projectTypes = null) {
   // Get project-specific filtering if not provided
-  if (!projectType) {
+  if (!projectTypes) {
     const detection = await detectProjectType(projectPath);
-    projectType = detection.type;
+    projectTypes = getAllDetectedTypes(detection);
   }
 
-  const projectSpecific = await getProjectSpecificFiltering(projectType);
+  const projectSpecific = await getProjectSpecificFiltering(projectTypes);
 
   // Merge project-specific filters with global config (same as in scanDirectoryRecursively)
   const effectiveConfig = {
@@ -314,15 +316,17 @@ async function estimateProjectTokens(projectPath, config, projectType = null) {
   }
 
   // Use adaptive polynomial estimation
-  const estimatedTokens = await estimateTokensWithPolynomial(projectType, totalSize);
+  // Token estimation uses the primary type for coefficient lookup
+  const primaryType = Array.isArray(projectTypes) ? projectTypes[0] : projectTypes;
+  const estimatedTokens = await estimateTokensWithPolynomial(primaryType, totalSize);
 
   return { estimatedTokens, totalSize, includedFiles };
 }
 
-async function processProjectFiles(repoPath, options, config, projectType = null) {
-  // Merge project-specific filtering rules (e.g., Cargo.lock for Rust)
-  if (projectType) {
-    const projectSpecific = await getProjectSpecificFiltering(projectType);
+async function processProjectFiles(repoPath, options, config, projectTypes = null) {
+  // Merge project-specific filtering rules for ALL detected types (polyglot monorepo support)
+  if (projectTypes) {
+    const projectSpecific = await getProjectSpecificFiltering(projectTypes);
     config = {
       ...config,
       dirsToIgnore: [...(config.dirsToIgnore || []), ...(projectSpecific.dirsToIgnore || [])],
@@ -371,7 +375,7 @@ async function processProjectFiles(repoPath, options, config, projectType = null
 
         if (filterResult.notFoundProfiles.length > 0) {
           errorMsg += `\n\n❌ Profile(s) not found: ${filterResult.notFoundProfiles.join(', ')}`;
-          errorMsg += `\n\n💡 Run 'eck-snapshot --profile' to see available profiles.`;
+          errorMsg += `\n\n💡 Run 'eck-snapshot snapshot --profile' to see available profiles.`;
           errorMsg += `\n   Or run 'eck-snapshot generate-profile-guide' to create profiles.`;
         } else if (filterResult.foundProfiles.length > 0) {
           errorMsg += `\n\n✓ Profile(s) found: ${filterResult.foundProfiles.join(', ')}`;
@@ -483,7 +487,7 @@ async function processProjectFiles(repoPath, options, config, projectType = null
           // Check if file should be focused (kept full)
           const isFocused = options.focus && micromatch.isMatch(normalizedPath, options.focus);
           if (!isFocused) {
-            content = await skeletonize(content, normalizedPath);
+            content = await skeletonize(content, normalizedPath, { preserveDocs: options.preserveDocs !== false });
           }
         }
 
@@ -531,7 +535,65 @@ async function processProjectFiles(repoPath, options, config, projectType = null
   }
 }
 
+/**
+ * Groups files by directory and packs them into chunks of a given maximum size.
+ * Preserves directory locality for better RAG retrieval in NotebookLM.
+ */
+function packFilesForNotebookLM(successfulFileObjects, maxChunkSizeBytes = 2.5 * 1024 * 1024) {
+  const dirGroups = new Map();
+
+  for (const fileObj of successfulFileObjects) {
+    const dir = fileObj.path.includes('/') ? fileObj.path.substring(0, fileObj.path.lastIndexOf('/')) : './';
+    if (!dirGroups.has(dir)) dirGroups.set(dir, { size: 0, files: [] });
+    const group = dirGroups.get(dir);
+    group.files.push(fileObj);
+    group.size += fileObj.size;
+  }
+
+  const sortedDirs = Array.from(dirGroups.keys()).sort();
+  const chunks = [];
+  let currentChunk = { size: 0, contentArray: [] };
+
+  for (const dir of sortedDirs) {
+    const group = dirGroups.get(dir);
+
+    if (group.size > maxChunkSizeBytes) {
+      // Directory too large — pack files individually
+      for (const fileObj of group.files) {
+        if (currentChunk.size + fileObj.size > maxChunkSizeBytes && currentChunk.contentArray.length > 0) {
+          chunks.push(currentChunk);
+          currentChunk = { size: 0, contentArray: [] };
+        }
+        currentChunk.contentArray.push(fileObj.content);
+        currentChunk.size += fileObj.size;
+      }
+    } else if (currentChunk.size + group.size <= maxChunkSizeBytes) {
+      // Directory fits in current chunk
+      for (const f of group.files) currentChunk.contentArray.push(f.content);
+      currentChunk.size += group.size;
+    } else {
+      // Start a new chunk
+      chunks.push(currentChunk);
+      currentChunk = { size: 0, contentArray: [] };
+      for (const f of group.files) currentChunk.contentArray.push(f.content);
+      currentChunk.size += group.size;
+    }
+  }
+
+  if (currentChunk.contentArray.length > 0) chunks.push(currentChunk);
+  return chunks;
+}
+
 export async function createRepoSnapshot(repoPath, options) {
+  // Handle linked project depth settings before processing
+  if (options.isLinkedProject) {
+    const depthCfg = getDepthConfig(options.linkDepth !== undefined ? options.linkDepth : 0);
+    if (depthCfg.skipContent) options.skipContent = true;
+    if (depthCfg.skeleton !== undefined) options.skeleton = depthCfg.skeleton;
+    if (depthCfg.preserveDocs !== undefined) options.preserveDocs = depthCfg.preserveDocs;
+    if (depthCfg.maxLinesPerFile !== undefined) options.maxLinesPerFile = depthCfg.maxLinesPerFile;
+  }
+
   const spinner = ora('Analyzing project...').start();
   try {
     // Ensure snapshots/ is in .gitignore to prevent accidental commits
@@ -570,7 +632,7 @@ export async function createRepoSnapshot(repoPath, options) {
         // Generate ready-to-copy command with all profiles
         const allProfilesString = profileNames.join(',');
         console.log(chalk.cyan('📝 Ready-to-Copy Command (all profiles):'));
-        console.log(chalk.bold(`\neck-snapshot --profile "${allProfilesString}"\n`));
+        console.log(chalk.bold(`\neck-snapshot '{"name": "eck_snapshot", "arguments": {"profile": "${allProfilesString}"}}'\n`));
         console.log(chalk.gray('💡 Tip: Copy the command above and remove profiles you don\'t need'));
         process.exit(0);
       } catch (error) {
@@ -629,19 +691,19 @@ export async function createRepoSnapshot(repoPath, options) {
       ...options // Command-line options have the final say
     };
 
-    // Detect architect modes
-    const isJas = options.jas;
-    const isJao = options.jao;
-    const isJaz = options.jaz;
-
-    // If NOT in Junior Architect mode, hide JA-specific documentation to prevent context pollution
-    if (!options.withJa && !isJas && !isJao && !isJaz) {
-      if (!config.filesToIgnore) config.filesToIgnore = [];
-      config.filesToIgnore.push(
-        'COMMANDS_REFERENCE.md',
-        'codex_delegation_snapshot.md'
-      );
-    }
+    // Detect architect modes
+    const isJas = options.jas;
+    const isJao = options.jao;
+    const isJaz = options.jaz;
+
+    // If NOT in Junior Architect mode, hide JA-specific documentation to prevent context pollution
+    if (!options.withJa && !isJas && !isJao && !isJaz) {
+      if (!config.filesToIgnore) config.filesToIgnore = [];
+      config.filesToIgnore.push(
+        'COMMANDS_REFERENCE.md',
+        'codex_delegation_snapshot.md'
+      );
+    }
 
     // Apply defaults for options that may not be provided via command line
     if (!config.output) {
@@ -658,7 +720,8 @@ export async function createRepoSnapshot(repoPath, options) {
       config.includeHidden = setupConfig.fileFiltering?.includeHidden ?? false;
     }
 
-    const estimation = await estimateProjectTokens(repoPath, config, projectDetection.type);
+    const allTypesForEstimation = getAllDetectedTypes(projectDetection);
+    const estimation = await estimateProjectTokens(repoPath, config, allTypesForEstimation);
     spinner.info(`Estimated project size: ~${Math.round(estimation.estimatedTokens).toLocaleString()} tokens.`);
 
     spinner.succeed('Creating snapshots...');
@@ -669,7 +732,8 @@ export async function createRepoSnapshot(repoPath, options) {
 
     let stats, contentArray, successfulFileObjects, allFiles, processedRepoPath;
 
-    const result = await processProjectFiles(repoPath, options, config, projectDetection.type);
+    const allTypes = getAllDetectedTypes(projectDetection);
+    const result = await processProjectFiles(repoPath, options, config, allTypes);
     stats = result.stats;
     contentArray = result.contentArray;
     successfulFileObjects = result.successfulFileObjects;
@@ -717,86 +781,200 @@ export async function createRepoSnapshot(repoPath, options) {
       let architectFilePath = null;
       let jaFilePath = null;
 
-      // File body always includes full content
-      let fileBody = (directoryTree ? `\n## Directory Structure\n\n\`\`\`\n${directoryTree}\`\`\`\n\n` : '') + contentArray.join('');
-
-      // Helper to write snapshot file
-      const writeSnapshot = async (suffix, isAgentMode) => {
-        // CHANGE: Force agent to FALSE for the main snapshot header.
-        // The snapshot is read by the Human/Senior Arch, not the Agent itself.
-        // The Agent reads CLAUDE.md.
-        const opts = { ...options, agent: false, jas: isJas, jao: isJao, jaz: isJaz };
-        const header = await generateEnhancedAIHeader({ stats, repoName, mode: 'file', eckManifest, options: opts, repoPath: processedRepoPath }, isGitRepo);
-
-        // Compact filename format: eck{ShortName}{timestamp}_{hash}_{suffix}.md
-        // getShortRepoName ensures Capitalized Start/End (e.g. SnaOt)
-        const shortHash = gitHash ? gitHash.substring(0, 7) : '';
-        const shortRepoName = getShortRepoName(repoName);
-
-        let fname = `eck${shortRepoName}${timestamp}`;
-        if (shortHash) fname += `_${shortHash}`;
-
-        // Add mode suffix
-        if (options.skeleton) {
-          fname += '_sk';
-        } else if (suffix) {
-          fname += suffix;
-        }
-
-        const fullContent = header + fileBody;
-        const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
-        fname += `_${sizeKB}kb.${fileExtension}`;
-        const fpath = path.join(outputPath, fname);
-        await fs.writeFile(fpath, fullContent);
-        console.log(`📄 Generated Snapshot: ${fname}`);
-
-        // --- FEATURE: Active Snapshot (.eck/lastsnapshot/) ---
-        // Only create .eck/lastsnapshot/ entries for the main snapshot
-        if (!isAgentMode) {
-          try {
-            const snapDir = path.join(originalCwd, '.eck', 'lastsnapshot');
-            await fs.mkdir(snapDir, { recursive: true });
-
-            // 1. Clean up OLD snapshots in this specific folder
-            // We keep AnswerToSA.md, but remove old snapshots and legacy answer.md
-            const existingFiles = await fs.readdir(snapDir);
-            for (const file of existingFiles) {
-              if ((file.startsWith('eck') && file.endsWith('.md')) || file === 'answer.md') {
-                await fs.unlink(path.join(snapDir, file));
-              }
-            }
-
-            // 2. Save the NEW specific named file
-            await fs.writeFile(path.join(snapDir, fname), fullContent);
-
-            console.log(chalk.cyan(`📋 Active snapshot updated in .eck/lastsnapshot/: ${fname}`));
-          } catch (e) {
-            // Non-critical failure
-            console.warn(chalk.yellow(`⚠️  Could not update .eck/lastsnapshot/: ${e.message}`));
-          }
-        }
-        // --------------------------------------------
-
-        return fpath;
-      };
-
-      // Generate snapshot file for ALL modes
-      if (isJas) {
-        architectFilePath = await writeSnapshot('_jas', true);
-      } else if (isJao) {
-        architectFilePath = await writeSnapshot('_jao', true);
-      } else if (isJaz) {
-        architectFilePath = await writeSnapshot('_jaz', true);
-      } else {
-        // Standard snapshot behavior
-        architectFilePath = await writeSnapshot('', false);
-
-        // --- File 2: Junior Architect Snapshot (legacy --with-ja support) ---
-        if (options.withJa && fileExtension === 'md') {
-          console.log('🖋️ Generating Junior Architect (_ja) snapshot...');
-          jaFilePath = await writeSnapshot('_ja', true);
-        }
-      }
+      // --- NotebookLM Chunked Export (Brain + Body) ---
+      if (options.notebooklm) {
+        const isArchitectMode = options.notebooklm === 'architect';
+        const modeName = isArchitectMode ? 'Architect' : 'Scout';
+        console.log(chalk.blue(`\n📚 Packing project for NotebookLM (${modeName} Mode)...`));
+
+        const chunks = packFilesForNotebookLM(successfulFileObjects);
+        const shortRepoName = getShortRepoName(repoName);
+        const absPath = processedRepoPath.replace(/\\/g, '/');
+        const filePrefix = isArchitectMode ? 'notelm' : 'booklm';
+
+        // Clean up old notebooklm chunks
+        try {
+          const existingFiles = await fs.readdir(outputPath);
+          for (const file of existingFiles) {
+            if (file.includes('_booklm_part') || file.includes('_notelm_part')) {
+              await fs.unlink(path.join(outputPath, file));
+            }
+          }
+        } catch (e) { /* ignore */ }
+
+        // --- Part 0: The Brain (Instructions + Manifests + Tree) ---
+        let part0 = `# 🧠 NOTEBOOKLM KNOWLEDGE BASE — PART 0 (THE BRAIN)\n`;
+        part0 += `**Project:** ${repoName}\n\n`;
+
+        if (isArchitectMode) {
+          part0 += `## YOUR ROLE: THE ARCHITECT\n`;
+          part0 += `You are the Senior Software Architect for this project. You have access to the entire codebase across the source documents (Parts 1-${chunks.length}).\n`;
+          part0 += `Analyze the codebase to solve complex structural problems, design new features, and propose refactoring strategies. Provide high-level guidance and precise code modifications.\n\n`;
+        } else {
+          part0 += `## YOUR ROLE: THE SCOUT\n`;
+          part0 += `You are an expert code analyst and retrieval specialist. You have access to the entire codebase across the source documents (Parts 1-${chunks.length}). Your goal is NOT to write code, but to help the primary Architect find the exact files they need.\n`;
+          part0 += `When asked about a feature, bug, or module — analyze the project structure and codebase, then output precise bash commands using \`eck-snapshot fetch\` so the user can extract the relevant files for their Architect agent.\n\n`;
+          part0 += `**RULES FOR FETCH COMMANDS:**\n`;
+          part0 += `1. Always start with \`cd ${absPath}\`\n`;
+          part0 += `2. Use relative glob patterns: \`eck-snapshot fetch "**/auth.js" "**/userController.js"\`\n`;
+          part0 += `3. Output the commands in a bash code block, accompanied by a brief explanation of why you selected those files.\n`;
+          part0 += `4. Include both directly relevant files AND adjacent files that provide context (imports, shared types, config).\n\n`;
+        }
+
+        // Add .eck manifests
+        if (eckManifest) {
+          part0 += `## 📑 Project Context & Manifests\n\n`;
+          if (eckManifest.context) part0 += `### CONTEXT\n${eckManifest.context}\n\n`;
+          if (eckManifest.techDebt) part0 += `### TECH DEBT\n${eckManifest.techDebt}\n\n`;
+          if (eckManifest.roadmap) part0 += `### ROADMAP\n${eckManifest.roadmap}\n\n`;
+          if (eckManifest.operations) part0 += `### OPERATIONS\n${eckManifest.operations}\n\n`;
+          // Include any dynamic .eck files
+          if (eckManifest.dynamicFiles) {
+            for (const [name, content] of Object.entries(eckManifest.dynamicFiles)) {
+              part0 += `### ${name.replace('.md', '').toUpperCase()}\n${content}\n\n`;
+            }
+          }
+        }
+
+        // Add full directory tree
+        if (directoryTree) {
+          part0 += `## 🌳 Global Directory Structure\n\`\`\`text\n${directoryTree}\n\`\`\`\n`;
+        }
+
+        const part0Name = `eck_${shortRepoName}_${filePrefix}_part0_BRAIN.md`;
+        await fs.writeFile(path.join(outputPath, part0Name), part0);
+        console.log(chalk.magenta(`   🧠 Part 0 (Brain): ${part0Name}`));
+
+        // --- Parts 1-N: The Body (Source Code Only) ---
+        for (let i = 0; i < chunks.length; i++) {
+          const chunk = chunks[i];
+          const header = `--- NOTEBOOKLM SOURCE CODE — PART ${i + 1} OF ${chunks.length} ---\n\n`;
+          const body = header + chunk.contentArray.join('');
+
+          const fname = `eck_${shortRepoName}_${filePrefix}_part${i + 1}.md`;
+          await fs.writeFile(path.join(outputPath, fname), body);
+          console.log(chalk.cyan(`   📄 Part ${i + 1}/${chunks.length}: ${fname} (${formatSize(chunk.size)})`));
+        }
+
+        console.log(chalk.green(`\n✅ NotebookLM export complete: 1 Brain + ${chunks.length} Source chunk(s) in ${outputPath}`));
+        console.log(chalk.gray(`   Upload all files as separate sources in NotebookLM (max 50 sources).`));
+
+        // Starter prompt for NotebookLM chat
+        console.log('\n🤖 STARTER PROMPT (paste as your FIRST message in NotebookLM):');
+        console.log('---------------------------------------------------');
+        console.log(chalk.cyan.bold('Read the source document ending in "_part0_BRAIN.md" completely before answering any questions. This document contains your core instructions, the project context, and the global directory tree. Acknowledge that you understand your role.\n'));
+
+        await saveGitAnchor(processedRepoPath);
+        return;
+      }
+
+      // --- Standard Snapshot Mode ---
+      let fileBody = '';
+      if (directoryTree) {
+        fileBody += `\n## Directory Structure\n\n\`\`\`\n${directoryTree}\`\`\`\n\n`;
+      }
+      if (!options.skipContent) {
+        fileBody += contentArray.join('');
+      }
+
+      // Helper to write snapshot file
+      const writeSnapshot = async (suffix, isAgentMode) => {
+        let header = '';
+        if (options.isLinkedProject) {
+          const absPath = processedRepoPath.replace(/\\/g, '/');
+          header = `# 🔗 LINKED PROJECT: [${repoName}]\n\n`;
+          header += `**ABSOLUTE PATH:** \`${absPath}\`\n`;
+          header += `**CROSS-CONTEXT MODE:** This is a linked companion project provided for reference. DO NOT generate code for it directly in your response unless explicitly asked. To inspect files inside this project, use your tool (or ask the user) to run ONE of the following commands:\n\n`;
+          header += `**Option A: Short format (Best for Windows PowerShell / CMD)**\n`;
+          header += `\`eck-snapshot fetch "${absPath}/src/example.js"\`\n\n`;
+          header += `**Option B: Pure JSON format (Best for Linux/Mac Bash/Zsh)**\n`;
+          header += `\`eck-snapshot '{"name": "eck_fetch", "arguments": {"patterns": ["${absPath}/src/example.js"]}}'\`\n\n`;
+          if (options.skipContent) {
+            header += `*(Source code omitted due to linkDepth=0. Directory structure only.)*\n\n`;
+          }
+        } else {
+          const opts = { ...options, agent: false, jas: isJas, jao: isJao, jaz: isJaz };
+          header = await generateEnhancedAIHeader({ stats, repoName, mode: 'file', eckManifest, options: opts, repoPath: processedRepoPath }, isGitRepo);
+        }
+
+        // Compact filename format
+        const shortHash = gitHash ? gitHash.substring(0, 7) : '';
+        const shortRepoName = getShortRepoName(repoName);
+
+        let fname = options.isLinkedProject ? `link_${shortRepoName}${timestamp}` : `eck${shortRepoName}${timestamp}`;
+        if (shortHash) fname += `_${shortHash}`;
+
+        // Add mode suffix
+        if (options.skeleton) {
+          fname += '_sk';
+        } else if (suffix) {
+          fname += suffix;
+        }
+
+        const fullContent = header + fileBody;
+        const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
+        fname += `_${sizeKB}kb.${fileExtension}`;
+        const fpath = path.join(outputPath, fname);
+        await fs.writeFile(fpath, fullContent);
+        const approxTokens = Math.round(fullContent.length / 4);
+        const tokensStr = approxTokens < 1000 ? `${approxTokens}` : `${(approxTokens / 1000).toFixed(1)}k`;
+        console.log(`📄 Generated Snapshot: ${fname} (${sizeKB} KB | ~${tokensStr} tokens)`);
+
+        // --- FEATURE: Active Snapshot ---
+        if (!isAgentMode) {
+          try {
+            if (options.isLinkedProject) {
+              // Link snapshots go to .eck/links/
+              const linksDir = path.join(originalCwd, '.eck', 'links');
+              await fs.mkdir(linksDir, { recursive: true });
+              await fs.writeFile(path.join(linksDir, fname), fullContent);
+              const approxTokens = Math.round(fullContent.length / 4);
+              const tokensStr = approxTokens < 1000 ? `${approxTokens}` : `${(approxTokens / 1000).toFixed(1)}k`;
+              console.log(chalk.cyan(`🔗 Link saved to .eck/links/${fname}`));
+              console.log(chalk.gray(`   Size: ${sizeKB} KB | ~${tokensStr} tokens`));
+            } else {
+              // Main snapshots go to .eck/lastsnapshot/
+              const snapDir = path.join(originalCwd, '.eck', 'lastsnapshot');
+              await fs.mkdir(snapDir, { recursive: true });
+
+              // Clean up OLD snapshots (keep AnswerToSA.md)
+              const existingFiles = await fs.readdir(snapDir);
+              for (const file of existingFiles) {
+                if ((file.startsWith('eck') && file.endsWith('.md')) || file === 'answer.md') {
+                  await fs.unlink(path.join(snapDir, file));
+                }
+              }
+
+              await fs.writeFile(path.join(snapDir, fname), fullContent);
+              console.log(chalk.cyan(`📋 Active snapshot updated in .eck/lastsnapshot/: ${fname}`));
+            }
+          } catch (e) {
+            // Non-critical failure
+            console.warn(chalk.yellow(`⚠️  Could not update active snapshot: ${e.message}`));
+          }
+        }
+        // --------------------------------------------
+
+        return fpath;
+      };
+
+      // Generate snapshot file for ALL modes
+      if (isJas) {
+        architectFilePath = await writeSnapshot('_jas', true);
+      } else if (isJao) {
+        architectFilePath = await writeSnapshot('_jao', true);
+      } else if (isJaz) {
+        architectFilePath = await writeSnapshot('_jaz', true);
+      } else {
+        // Standard snapshot behavior
+        architectFilePath = await writeSnapshot('', false);
+
+        // --- File 2: Junior Architect Snapshot (legacy --with-ja support) ---
+        if (options.withJa && fileExtension === 'md') {
+          console.log('🖋️ Generating Junior Architect (_ja) snapshot...');
+          jaFilePath = await writeSnapshot('_ja', true);
+        }
+      }
 
       // Save git anchor for future delta updates
       await saveGitAnchor(processedRepoPath);
@@ -816,20 +994,48 @@ export async function createRepoSnapshot(repoPath, options) {
       console.log('🔐 Scanning for confidential files...');
       const confidentialFiles = await scanEckForConfidentialFiles(processedRepoPath, config);
 
-      let claudeMode = 'coder';
-      if (isJas) claudeMode = 'jas';
-      if (isJao) claudeMode = 'jao';
-      if (isJaz) claudeMode = 'jaz';
-
-      // Claude Code exclusively uses CLAUDE.md
-      if (isJas || isJao || (!isJaz && !options.withJa)) {
-        await updateClaudeMd(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
-      }
-
-      // OpenCode exclusively uses AGENTS.md
-      if (isJaz || (!isJas && !isJao && !options.withJa)) {
-        await generateOpenCodeAgents(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
-      }
+      let claudeMode = 'coder';
+      if (isJas) claudeMode = 'jas';
+      if (isJao) claudeMode = 'jao';
+      if (isJaz) claudeMode = 'jaz';
+
+      // Claude Code exclusively uses CLAUDE.md
+      if (isJas || isJao || (!isJaz && !options.withJa)) {
+        await updateClaudeMd(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
+        // Ensure .mcp.json with eck-core is present so Claude Code agents have MCP tools
+        try {
+          const mcpCreated = await ensureProjectMcpConfig(processedRepoPath);
+          if (mcpCreated) {
+            console.log(chalk.green('🔌 Created .mcp.json with eck-core MCP server'));
+          }
+        } catch (e) {
+          // Non-critical — agent can still use manual fallback
+        }
+      }
+
+      // OpenCode exclusively uses AGENTS.md
+      if (isJaz || (!isJas && !isJao && !options.withJa)) {
+        await generateOpenCodeAgents(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
+        // Ensure local opencode.json has eck-core MCP server
+        try {
+          const mcpCreated = await ensureProjectOpenCodeConfig(processedRepoPath);
+          if (mcpCreated) {
+            console.log(chalk.green('🔌 Added eck-core to local opencode.json'));
+          }
+        } catch (e) {
+          // Non-critical — agent can still use manual fallback
+        }
+
+        // Ensure Codex config if the directory exists
+        try {
+          const codexMcpCreated = await ensureProjectCodexConfig(processedRepoPath);
+          if (codexMcpCreated) {
+            console.log(chalk.green('🔌 Added eck-core to .codex/config.toml'));
+          }
+        } catch (e) {
+          // Non-critical
+        }
+      }
 
       // --- Combined Report ---
       console.log('\n✅ Snapshot generation complete!');
@@ -924,6 +1130,14 @@ export async function createRepoSnapshot(repoPath, options) {
         console.log('   Replace [ACTUAL_TOKENS_HERE] with the real token count from your LLM');
       }
 
+      // Output AI Prompt Suggestion for stubborn LLMs
+      console.log('\n🤖 AI PROMPT SUGGESTION (Crucial for ChatGPT, helpful for others):');
+      console.log('---------------------------------------------------');
+      console.log(chalk.yellow('💡 Tip: Gemini and Grok handle large files best. ChatGPT works but can be slow.'));
+      console.log('If your AI ignores the file instructions and acts as an external reviewer,');
+      console.log('copy and paste this exact text as your FIRST prompt along with the snapshot file:\n');
+      console.log(chalk.cyan.bold('Read the SYSTEM DIRECTIVE at the very beginning of the attached file. Immediately assume the role of Senior Architect as instructed, then await my first task.\n'));
+
     } finally {
       process.chdir(originalCwd); // Final reset back to original CWD
     }