@xelth/eck-snapshot 5.9.0 → 6.6.0

package/src/cli/commands/createSnapshot.js

@@ -15,16 +15,18 @@ import {
   scanDirectoryRecursively, loadGitignore, readFileWithSizeCheck,
   generateDirectoryTree, loadConfig, displayProjectInfo, loadProjectEckManifest,
   ensureSnapshotsInGitignore, initializeEckManifest, generateTimestamp,
-  getShortRepoName, SecretScanner
+  getShortRepoName, SecretScanner, getProjectFiles, readMlModelMetadata
 } 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
@@ -199,47 +201,7 @@ function generateClaudeMdContent(confidentialFiles, repoPath) {
   return content.join('\n');
 }
 
-// Global hard-ignore patterns (must match exactly in scanDirectoryRecursively)
-const GLOBAL_HARD_IGNORE_DIRS = ['node_modules', '.git', '.idea', '.vscode'];
-const GLOBAL_HARD_IGNORE_FILES = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'go.sum'];
-
-function shouldHardIgnore(entryName, isDirectory) {
-  if (isDirectory) {
-    return GLOBAL_HARD_IGNORE_DIRS.includes(entryName);
-  }
-  return GLOBAL_HARD_IGNORE_FILES.includes(entryName);
-}
-
-async function getProjectFiles(projectPath, config) {
-  const isGitRepo = await checkGitRepository(projectPath);
-  if (isGitRepo) {
-    const { stdout } = await execa('git', ['ls-files'], { cwd: projectPath });
-    const gitFiles = stdout.split('\n').filter(Boolean);
-
-    // Build effective dirsToIgnore list (global hard-ignores + config)
-    const dirsToIgnore = [...GLOBAL_HARD_IGNORE_DIRS, ...(config.dirsToIgnore || []).map(d => d.replace(/\/$/, ''))];
-    const filesToIgnore = [...GLOBAL_HARD_IGNORE_FILES, ...(config.filesToIgnore || [])];
-    const extensionsToIgnore = config.extensionsToIgnore || [];
-
-    const filteredFiles = gitFiles.filter(file => {
-      if (isHiddenPath(file)) return false;
-      const fileName = file.split('/').pop();
-      const fileExt = path.extname(fileName);
-      // Check if any parent directory should be ignored
-      const pathParts = file.split('/');
-      for (let i = 0; i < pathParts.length - 1; i++) {
-        if (dirsToIgnore.includes(pathParts[i])) return false;
-      }
-      // Check filesToIgnore
-      if (filesToIgnore.includes(fileName)) return false;
-      // Check extensionsToIgnore
-      if (fileExt && extensionsToIgnore.includes(fileExt)) return false;
-      return true;
-    });
-    return filteredFiles;
-  }
-  return scanDirectoryRecursively(projectPath, config);
-}
+// getProjectFiles is now imported from fileUtils.js
 
 async function getGitCommitHash(projectPath) {
   try {
@@ -254,14 +216,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 +276,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 +335,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(', ')}`;
@@ -430,8 +394,12 @@ async function processProjectFiles(repoPath, options, config, projectType = null
           return null;
         }
 
-        // Check if binary file
-        if (isBinaryPath(filePath)) {
+        const mlExt = path.extname(filePath).toLowerCase();
+        const ML_EXTENSIONS = ['.safetensors', '.onnx', '.pt', '.pth', '.h5', '.pb', '.bin', '.ckpt', '.gguf'];
+        const isMlModel = ML_EXTENSIONS.includes(mlExt);
+
+        // Check if binary file (bypass if it's an ML model we want to peek into)
+        if (isBinaryPath(filePath) && !isMlModel) {
           stats.binaryFiles++;
           trackSkippedFile(normalizedPath, 'Binary files');
           return null;
@@ -457,13 +425,18 @@ async function processProjectFiles(repoPath, options, config, projectType = null
         stats.totalSize += fileStats.size;
 
         const maxFileSize = parseSize(config.maxFileSize);
-        if (fileStats.size > maxFileSize) {
-          stats.oversizedFiles++;
-          trackSkippedFile(normalizedPath, `File too large (${formatSize(fileStats.size)} > ${formatSize(maxFileSize)})`);
-          return null;
-        }
+        let content;
 
-        let content = await readFileWithSizeCheck(fullPath, maxFileSize);
+        if (isMlModel) {
+          content = await readMlModelMetadata(fullPath);
+        } else {
+          if (fileStats.size > maxFileSize) {
+            stats.oversizedFiles++;
+            trackSkippedFile(normalizedPath, `File too large (${formatSize(fileStats.size)} > ${formatSize(maxFileSize)})`);
+            return null;
+          }
+          content = await readFileWithSizeCheck(fullPath, maxFileSize);
+        }
 
         // Security scan for secrets
         if (config.security?.scanForSecrets !== false) {
@@ -476,14 +449,13 @@ async function processProjectFiles(repoPath, options, config, projectType = null
         }
 
         stats.includedFiles++;
-        stats.processedSize += fileStats.size;
 
         // Apply skeletonization if enabled
         if (options.skeleton) {
           // 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 });
           }
         }
 
@@ -498,10 +470,14 @@ async function processProjectFiles(repoPath, options, config, projectType = null
           }
         }
 
+        const formattedContent = `--- File: /${normalizedPath} ---\n\n${outputBody}\n\n`;
+        const finalSize = Buffer.byteLength(formattedContent, 'utf-8');
+        stats.processedSize += finalSize;
+
         return {
-          content: `--- File: /${normalizedPath} ---\n\n${outputBody}\n\n`,
+          content: formattedContent,
           path: normalizedPath,
-          size: fileStats.size
+          size: finalSize
         };
       } catch (error) {
         stats.errors.push(`${normalizedPath}: ${error.message}`);
@@ -531,7 +507,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/scout project depth settings before processing
+  if (options.isLinkedProject || (options.notebooklm && options.linkDepth !== undefined)) {
+    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 +604,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 +663,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 +692,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 +704,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 +753,230 @@ 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 mode = options.notebooklm; // 'hybrid', 'link', 'scout', 'architect'
+        console.log(chalk.blue(`\n📚 Packing project for NotebookLM (${mode.toUpperCase()} Mode)...`));
+
+        // If options.skipContent is true (Depth 0), chunks will be empty, only part0_BRAIN is generated
+        const chunks = options.skipContent ? [] : packFilesForNotebookLM(successfulFileObjects);
+        const shortRepoName = getShortRepoName(repoName);
+        const absPath = processedRepoPath.replace(/\\/g, '/');
+        const filePrefix = mode; // e.g. hybrid, link, scout
+
+        // Clean up old notebooklm chunks for this prefix
+        try {
+          const existingFiles = await fs.readdir(outputPath);
+          for (const file of existingFiles) {
+            if (file.includes(`_${filePrefix}_part`)) {
+              await fs.unlink(path.join(outputPath, file));
+            }
+          }
+        } catch (e) { /* ignore */ }
+
+        let systemPrompt = '';
+        if (mode === 'architect') {
+          systemPrompt += `You are the Senior Software Architect for this project.\n`;
+          systemPrompt += `Analyze the provided source documents to solve complex structural problems, design new features, and propose refactoring strategies.\n\n`;
+          systemPrompt += `RULES FOR CODE GENERATION:\n`;
+          systemPrompt += `1. Output precise code modifications using Eck-Protocol v2.\n`;
+          systemPrompt += `2. Wrap the entire response in quadruple backticks (\`\`\`\`).\n`;
+          systemPrompt += `3. Use \`<file path="..." action="replace">\` XML tags for files.\n`;
+          systemPrompt += `4. Always consult the BRAIN document (part 0) before answering to understand project constraints.\n`;
+          systemPrompt += `5. ANTI-CONTAMINATION: Verify that any new file uploads belong to this project context. If not, WARN the user and stop.\n`;
+        } else if (mode === 'hybrid') {
+          systemPrompt += `You are a Senior Software Architect managing a multi-repository ecosystem.\n\n`;
+          systemPrompt += `YOUR DATA SOURCES:\n`;
+          systemPrompt += `1. Primary Project (part0_BRAIN, part1, etc.): The main repository you are actively developing.\n`;
+          systemPrompt += `2. Linked Projects (link_part*): Companion repositories (e.g., backend + mobile). You CAN modify code here if cross-project sync is needed.\n`;
+          systemPrompt += `3. Scouted Projects (scout_part*): External repositories loaded STRICTLY for read-only reference. NEVER write code for scouted projects.\n\n`;
+          systemPrompt += `RULES:\n`;
+          systemPrompt += `- Use Eck-Protocol v2 format (quadruple backticks \`\`\`\`, <file> tags) for ALL code generation.\n`;
+          systemPrompt += `- If modifying a Linked Project, clearly specify the absolute project path in the <file> tag.\n`;
+          systemPrompt += `- If you need missing file contents from linked/scouted projects (because they were truncated/skeletonized), output bash commands to fetch them: \`cd /path/to/project && eck-snapshot fetch "**/api.rs"\`.\n`;
+          systemPrompt += `- ANTI-CONTAMINATION: Verify that any new file uploads belong to your known primary/linked contexts. If not, WARN the user and stop.\n`;
+        }
+
+        // --- Part 0: The Brain (Manifests + Tree ONLY) ---
+        let part0 = `# 🧠 NOTEBOOKLM KNOWLEDGE BASE — PART 0 (THE BRAIN)\n`;
+        if (mode === 'link') {
+          part0 += `**Linked Companion Project:** ${repoName}\n**Absolute Path:** ${absPath}\n`;
+          part0 += `*(Note: This is a linked project. You can modify code here if necessary for cross-project integration.)*\n\n`;
+        } else if (mode === 'scout') {
+          part0 += `**Scouted External Project:** ${repoName}\n**Absolute Path:** ${absPath}\n`;
+          part0 += `*(Note: STRICTLY READ-ONLY reference project. Do not write code for this project.)*\n\n`;
+        } else {
+          part0 += `**Primary Project:** ${repoName}\n**Absolute Path:** ${absPath}\n\n`;
+          part0 += `*(Note: Your core instructions are configured in the Chat Settings / Custom Instructions)*\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`;
+          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 in ${outputPath}`));
+        
+        // --- CONSOLE OUTPUT INSTRUCTIONS ---
+        console.log('\n⚙️  ' + chalk.yellow.bold(`NOTEBOOKLM UPLOAD INSTRUCTIONS (${mode.toUpperCase()} MODE):`));
+        console.log('---------------------------------------------------');
+        
+        if (mode === 'hybrid' || mode === 'architect') {
+          console.log(`1. Open NotebookLM and go to: ${chalk.bold('Chat konfigurieren -> Benutzerdefiniert')} (Configure Chat -> Custom)`);
+          console.log(`2. Copy the text below and paste it into the prompt window:`);
+          console.log('\n' + chalk.bgWhite.black(' --- COPY BELOW THIS LINE --- '));
+          console.log(chalk.cyan(systemPrompt));
+          console.log(chalk.bgWhite.black(' --- COPY ABOVE THIS LINE --- ') + '\n');
+          console.log(`3. Upload Part 0 and Parts 1-${chunks.length} as sources.`);
+          if (mode === 'hybrid') {
+            console.log(`4. Upload your linked/scouted files as additional sources.`);
+          }
+        } else {
+          // Link or Scout mode
+          console.log(`1. Upload Part 0${chunks.length > 0 ? ` and Parts 1-${chunks.length}` : ''} as sources to your EXISTING NotebookLM project.`);
+          console.log(`2. No new System Prompt is needed. The primary project's prompt already handles ${mode} files.`);
+        }
+
+        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 +996,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 +1132,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
     }