@xelth/eck-snapshot 4.1.0 → 4.2.1

package/README.md

@@ -12,7 +12,7 @@ This tool is built for a modern workflow where you act as the architect, guiding
 `eckSnapshot` is designed to support a two-part AI workflow for maximum efficiency and quality:
 
 1.  **The Architect LLM (Gemini, GPT-4, Grok):** A model with a large context window. You provide it with a snapshot of your project, and it analyzes the codebase to create a high-level plan for new features or refactoring.
-2.  **The Coder LLM (Claude Code, OpenAI Codex):** A model specialized in writing and modifying code. It takes the detailed instructions generated by the Architect and performs the hands-on coding tasks.
+2.  **The Coder LLM (Claude Code, Minimax, etc.):** A model specialized in writing and modifying code. It takes the detailed instructions generated by the Architect and performs the hands-on coding tasks.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories and directories. Optimized for AI context and LLM workflows.",
   "main": "index.js",
   "type": "module",
@@ -19,8 +19,7 @@
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
-    "docs:auto": "node index.js docs-auto",
-    "test:gpt": "vitest src/services/gptService.test.js"
+    "docs:auto": "node index.js docs-auto"
   },
   "author": "xelth-com",
   "license": "MIT",
@@ -41,15 +40,20 @@
     "inquirer": "^9.2.20",
     "is-binary-path": "^2.1.0",
     "micromatch": "^4.0.8",
+    "minimatch": "^9.0.3",
     "ora": "^8.1.0",
     "p-limit": "^5.0.0",
     "p-retry": "^6.2.1",
+    "which": "^4.0.0"
+  },
+  "optionalDependencies": {
     "tree-sitter": "^0.25.0",
     "tree-sitter-c": "^0.24.1",
+    "tree-sitter-go": "^0.23.4",
     "tree-sitter-java": "^0.23.5",
     "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-python": "^0.25.0",
-    "which": "^4.0.0"
+    "tree-sitter-rust": "^0.23.2"
   },
   "devDependencies": {
     "jsdom": "^24.0.0",

package/setup.json

@@ -231,16 +231,13 @@
   },
   "contextProfiles": {
     "backend": {
-      "description": "Backend API, database, business logic",
+      "description": "Backend API, services, business logic",
       "include": [
         "packages/backend/**",
-        "packages/core/**",
-        "knexfile.js",
-        "migrations/**"
+        "packages/core/**"
       ],
       "exclude": [
         "**/*.test.*",
-        "**/*.sqlite*",
         "node_modules/**"
       ]
     },
@@ -301,8 +298,7 @@
       "description": "Database schema and migrations only",
       "include": [
         "**/migrations/**",
-        "**/knexfile.js",
-        "**/schema.sql"
+        "**/schema/**"
       ]
     },
     "deployment": {
@@ -544,6 +540,10 @@
     "maxDepth": 10,
     "concurrency": 10
   },
+  "security": {
+    "scanForSecrets": true,
+    "_comment": "Automatically detects and redacts API keys, tokens, and credentials in snapshots to prevent accidental exposure"
+  },
   "output": {
     "defaultFormat": "md",
     "defaultPath": "./.eck/snapshots",
@@ -671,25 +671,6 @@
           "no hardware debugging interfaces"
         ]
       },
-      "ci_cd": {
-        "active": false,
-        "name": "CI/CD Pipeline Agent (AGENT_CI_CD)",
-        "description": "Automated testing and deployment pipeline",
-        "guiSupport": false,
-        "capabilities": [
-          "npm ci",
-          "npm test",
-          "npm run build",
-          "docker build",
-          "artifact generation"
-        ],
-        "restrictions": [
-          "no interactive commands",
-          "no GUI applications",
-          "no watch modes",
-          "no development servers"
-        ]
-      },
       "gemini_wsl": {
         "active": true,
         "name": "Gemini WSL Agent (Junior Architect)",
@@ -763,7 +744,6 @@
       "envScanRequest": "src/templates/envScanRequest.md",
       "gitWorkflow": "src/templates/gitWorkflow.md",
       "multiAgent": "src/templates/multiAgent.md",
-      "vectorMode": "src/templates/vectorMode.md",
       "agent": "src/templates/agent-prompt.template.md"
     }
   },
@@ -802,11 +782,11 @@
       },
       "database_expert": {
         "active": true,
-        "modelName": "GPT-4/Claude",
+        "modelName": "Claude",
         "role": "Database Specialist",
         "strengths": [
-          "PostgreSQL optimization",
-          "Knex migrations",
+          "Schema design",
+          "Query optimization",
           "data integrity"
         ]
       },

package/src/cli/cli.js

@@ -13,14 +13,13 @@ import { pruneSnapshot } from './commands/pruneSnapshot.js';
 import { generateConsilium } from './commands/consilium.js';
 import { detectProject, testFileParsing } from './commands/detectProject.js';
 import { trainTokens, showTokenStats } from './commands/trainTokens.js';
-import { askGpt } from './commands/askGpt.js';
-import { ask as askGptService } from '../services/gptService.js';
 import { executePrompt, executePromptWithSession } from '../services/claudeCliService.js';
 import { detectProfiles } from './commands/detectProfiles.js';
 import { generateProfileGuide } from './commands/generateProfileGuide.js';
 import { setupGemini } from './commands/setupGemini.js';
 import { generateAutoDocs } from './commands/autoDocs.js';
 import { showFile } from './commands/showFile.js';
+import { runDoctor } from './commands/doctor.js';
 import inquirer from 'inquirer';
 import ora from 'ora';
 import { execa } from 'execa';
@@ -112,7 +111,7 @@ Option C: Using Profiles
 
 - restore:            Restore files from a snapshot to disk.
 - prune:              Use AI to shrink a snapshot file by importance.
-- ask-gpt/claude:     Delegate tasks to agents directly (via API).
+- ask-claude:        Delegate tasks to Claude CLI agent.
 - setup-gemini:       Configure gemini-cli integration.
 `;
 
@@ -246,47 +245,6 @@ Creating Custom Profiles:
       console.log(JSON.stringify(result, null, 2));
     });
 
-  program
-    .command('ask-gpt')
-    .description('Delegate tasks to OpenAI Codex agent with automatic authentication')
-    .argument('<payload>', 'JSON payload string (e.g. \'{"objective": "Calculate 5+2"}\')')
-    .option('-v, --verbose', 'Enable verbose logging and detailed execution output')
-    .option('--model <name>', 'Model to use (default: gpt-5-codex)', 'gpt-5-codex')
-    .option('--reasoning <level>', 'Reasoning level: low, medium, high (default: high)', 'high')
-    .action((payloadArg, cmd) => askGpt(payloadArg, cmd))
-    .addHelpText('after', `
-Examples:
-  Ask a simple question:
-    eck-snapshot ask-gpt '{"objective": "What is 5+2?"}'
-
-  Request code changes with context:
-    eck-snapshot ask-gpt '{
-      "target_agent": "local_dev",
-      "task_id": "feature-123",
-      "payload": {
-        "objective": "Add error handling to login function",
-        "files_to_modify": [{"path": "src/auth.js", "action": "modify"}]
-      },
-      "post_execution_steps": {
-        "journal_entry": {
-          "type": "feat",
-          "scope": "auth",
-          "summary": "Add error handling"
-        }
-      }
-    }' --verbose
-
-Prerequisites:
-  1. Install Codex CLI: npm install -g @openai/codex
-  2. Login: codex login (requires ChatGPT Plus/Pro subscription)
-  3. The command automatically loads .eck project context
-
-Authentication:
-  - Uses your existing 'codex login' credentials
-  - Auto-retries on authentication errors
-  - Supports ChatGPT Plus/Pro subscriptions
-`);
-
   // Project detection command
   program
     .command('detect')
@@ -344,16 +302,8 @@ Authentication:
         const result = await executePrompt(prompt, options.continue);
         console.log(JSON.stringify(result, null, 2));
       } catch (error) {
-        console.warn(`⚠️ Claude failed: ${error.message}`);
-        console.log('🔄 Failing over to GPT for task...');
-        try {
-          const payload = (typeof prompt === 'string' && prompt.startsWith('{')) ? prompt : JSON.stringify({ objective: prompt });
-          const gptResult = await askGptService(payload, { verbose: false });
-          console.log(JSON.stringify(gptResult, null, 2));
-        } catch (gptError) {
-          console.error('Failed to execute prompt with both Claude and GPT:', gptError.message);
-          process.exit(1);
-        }
+        console.error(`Failed to execute prompt: ${error.message}`);
+        process.exit(1);
       }
     });
 
@@ -413,5 +363,12 @@ Authentication:
     .argument('<filePaths...>', 'Space-separated paths to files')
     .action(showFile);
 
+  // Doctor command (health check for manifests)
+  program
+    .command('doctor')
+    .description('Check project health and detect unfinished manifest stubs')
+    .argument('[repoPath]', 'Path to the repository', process.cwd())
+    .action(runDoctor);
+
   program.parse(process.argv);
 }

package/src/cli/commands/autoDocs.js

@@ -19,38 +19,7 @@ export async function generateAutoDocs() {
       await fs.access(extensionsDir);
     } catch (error) {
       console.log(`Extensions directory not found at: ${extensionsDir}`);
-      console.log('Creating example structure...');
-
-      // Create the directory structure
-      await fs.mkdir(extensionsDir, { recursive: true });
-
-      // Create a sample gemini-extension.json file for demonstration
-      const sampleExtension = {
-        name: "sample-extension",
-        description: "Sample Gemini extension for demonstration",
-        commands: [
-          {
-            name: "sample-command",
-            description: "A sample command for testing auto-docs",
-            usage: "sample-command [options]",
-            examples: ["sample-command --help"]
-          }
-        ],
-        tools: [
-          {
-            name: "sample-tool",
-            description: "A sample tool for testing auto-docs",
-            usage: "Use this tool for sample operations"
-          }
-        ]
-      };
-
-      await fs.writeFile(
-        path.join(extensionsDir, 'sample-extension.json'),
-        JSON.stringify(sampleExtension, null, 2)
-      );
-
-      console.log('Created sample extension at:', path.join(extensionsDir, 'sample-extension.json'));
+      return;
     }
 
     // Read all JSON files in the extensions directory

package/src/cli/commands/createSnapshot.js

@@ -8,12 +8,14 @@ import zlib from 'zlib';
 import { promisify } from 'util';
 import ora from 'ora';
 import micromatch from 'micromatch';
+import chalk from 'chalk';
 
 import {
   parseSize, formatSize, matchesPattern, checkGitRepository,
   scanDirectoryRecursively, loadGitignore, readFileWithSizeCheck,
   generateDirectoryTree, loadConfig, displayProjectInfo, loadProjectEckManifest,
-  ensureSnapshotsInGitignore, initializeEckManifest
+  ensureSnapshotsInGitignore, initializeEckManifest, generateTimestamp,
+  SecretScanner
 } from '../../utils/fileUtils.js';
 import { detectProjectType, getProjectSpecificFiltering } from '../../utils/projectDetector.js';
 import { estimateTokensWithPolynomial, generateTrainingCommand } from '../../utils/tokenEstimator.js';
@@ -131,11 +133,77 @@ import { generateEnhancedAIHeader } from '../../utils/aiHeader.js';
 
 const gzip = promisify(zlib.gzip);
 
+/**
+ * Check if a path is a hidden directory/folder (starts with '.')
+ * This excludes all hidden folders like .git, .eck, .claude, .gemini from snapshots
+ * @param {string} filePath - File or directory path
+ * @returns {boolean} True if path is hidden
+ */
+function isHiddenPath(filePath) {
+  // Check if path or any parent directory starts with '.'
+  const parts = filePath.split('/');
+  return parts.some(part => part.startsWith('.'));
+}
+
+/**
+ * Scans the .eck directory for confidential files
+ * @param {string} projectPath - Path to the project
+ * @param {object} config - Configuration object
+ * @returns {Promise<string[]>} Array of confidential file paths
+ */
+async function scanEckForConfidentialFiles(projectPath, config) {
+  const eckPath = path.join(projectPath, '.eck');
+
+  try {
+    await fs.access(eckPath);
+  } catch {
+    return []; // .eck directory doesn't exist
+  }
+
+  const result = await scanDirectoryRecursively(eckPath, config, projectPath, null, true);
+  return result.confidentialFiles || [];
+}
+
+/**
+ * Generates CLAUDE.md content with references to confidential files
+ * @param {string[]} confidentialFiles - Array of confidential file paths
+ * @param {string} repoPath - Path to the repository
+ * @returns {string} CLAUDE.md content
+ */
+function generateClaudeMdContent(confidentialFiles, repoPath) {
+  const content = [`# Project Access & Credentials Reference`, ``];
+
+  if (confidentialFiles.length === 0) {
+    content.push('No confidential files found in .eck directory.');
+    return content.join('\n');
+  }
+
+  content.push('## Access & Credentials');
+  content.push('');
+  content.push('The following confidential files are available locally but not included in snapshots:');
+  content.push('');
+
+  for (const file of confidentialFiles) {
+    const absolutePath = path.join(repoPath, file);
+    const fileName = path.basename(file);
+    content.push(`- **${fileName}**: \`${absolutePath}\``);
+  }
+
+  content.push('');
+  content.push('> **Note**: These files contain sensitive information and should only be accessed when needed.');
+  content.push('> They are excluded from snapshots for security reasons but can be referenced on demand.');
+
+  return content.join('\n');
+}
+
 async function getProjectFiles(projectPath, config) {
   const isGitRepo = await checkGitRepository(projectPath);
   if (isGitRepo) {
     const { stdout } = await execa('git', ['ls-files'], { cwd: projectPath });
-    return stdout.split('\n').filter(Boolean);
+    const gitFiles = stdout.split('\n').filter(Boolean);
+    // Filter out hidden directories/files (starting with '.')
+    const filteredFiles = gitFiles.filter(file => !isHiddenPath(file));
+    return filteredFiles;
   }
   return scanDirectoryRecursively(projectPath, config);
 }
@@ -231,6 +299,7 @@ async function processProjectFiles(repoPath, options, config, projectType = null
     ignoredFiles: 0,
     totalSize: 0,
     processedSize: 0,
+    secretsRedacted: 0,
     errors: [],
     skipReasons: new Map(),
     skippedFilesDetails: new Map()
@@ -242,6 +311,11 @@ async function processProjectFiles(repoPath, options, config, projectType = null
     console.log('🔍 Scanning repository...');
     let allFiles = await getProjectFiles(repoPath, config);
 
+    // Filter the raw file list immediately so ignored files don't show up in the Tree
+    if (config.filesToIgnore && config.filesToIgnore.length > 0) {
+      allFiles = allFiles.filter(file => !matchesPattern(file, config.filesToIgnore));
+    }
+
     if (options.profile) {
       console.log(`Applying profile filter: '${options.profile}'...`);
       allFiles = await applyProfileFilter(allFiles, options.profile, repoPath);
@@ -277,6 +351,13 @@ async function processProjectFiles(repoPath, options, config, projectType = null
       progressBar.update(index + 1, { filename: normalizedPath.slice(0, 50) });
 
       try {
+        // Skip all hidden directories and files (starting with '.')
+        if (isHiddenPath(normalizedPath)) {
+          stats.ignoredFiles++;
+          trackSkippedFile(normalizedPath, 'Hidden directories/files');
+          return null;
+        }
+
         // Check if file should be ignored by directory patterns
         if (config.dirsToIgnore.some(dir => normalizedPath.startsWith(dir))) {
           stats.ignoredFiles++;
@@ -325,6 +406,17 @@ async function processProjectFiles(repoPath, options, config, projectType = null
         }
 
         let content = await readFileWithSizeCheck(fullPath, maxFileSize);
+
+        // Security scan for secrets
+        if (config.security?.scanForSecrets !== false) {
+          const scanResult = SecretScanner.redact(content, normalizedPath);
+          if (scanResult.found.length > 0) {
+            stats.secretsRedacted += scanResult.found.length;
+            console.log(chalk.yellow(`\n  ⚠️  Security: Found ${scanResult.found.join(', ')} in ${normalizedPath}. Redacting...`));
+            content = scanResult.content;
+          }
+        }
+
         stats.includedFiles++;
         stats.processedSize += fileStats.size;
 
@@ -399,8 +491,8 @@ export async function createRepoSnapshot(repoPath, options) {
         if (status) {
           spinner.text = 'Unstaged changes detected. Auto-committing...';
           await execa('git', ['add', '.'], { cwd: repoPath });
-          const timestamp = new Date().toISOString().slice(0, 19).replace('T', '_').replace(/:/g, '-');
-          await execa('git', ['commit', '-m', `chore(snapshot): Auto-commit before snapshot [${timestamp}]`], { cwd: repoPath });
+          const commitTimestamp = generateTimestamp();
+          await execa('git', ['commit', '-m', `chore(snapshot): Auto-commit before snapshot [${commitTimestamp}]`], { cwd: repoPath });
           spinner.info('Auto-commit complete.');
         } else {
           // No changes, do nothing. Logging this would be too verbose.
@@ -434,6 +526,15 @@ export async function createRepoSnapshot(repoPath, options) {
       ...options // Command-line options have the final say
     };
 
+    // If NOT in Junior Architect mode, hide JA-specific documentation to prevent context pollution
+    if (!options.withJa) {
+      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) {
       config.output = setupConfig.output?.defaultPath || './snapshots';
@@ -468,8 +569,8 @@ export async function createRepoSnapshot(repoPath, options) {
     process.chdir(processedRepoPath); // Go back to repo path for git hash and tree
 
     try {
-      // --- Common Data --- 
-      const timestamp = new Date().toISOString().slice(0, 19).replace('T', '_').replace(/:/g, '-');
+      // --- Common Data ---
+      const timestamp = generateTimestamp();
       const repoName = path.basename(processedRepoPath);
       const gitHash = await getGitCommitHash(processedRepoPath);
       const fileExtension = options.format || config.defaultFormat || 'md';
@@ -531,6 +632,17 @@ export async function createRepoSnapshot(repoPath, options) {
       // Save git anchor for future delta updates
       await saveGitAnchor(processedRepoPath);
 
+      // --- Generate CLAUDE.md with confidential file references ---
+      console.log('🔐 Scanning for confidential files in .eck directory...');
+      const confidentialFiles = await scanEckForConfidentialFiles(processedRepoPath, config);
+
+      if (confidentialFiles.length > 0) {
+        const claudeMdContent = generateClaudeMdContent(confidentialFiles, processedRepoPath);
+        const claudeMdPath = path.join(processedRepoPath, 'CLAUDE.md');
+        await fs.writeFile(claudeMdPath, claudeMdContent);
+        console.log(`📝 Generated CLAUDE.md with ${confidentialFiles.length} confidential file reference(s)`);
+      }
+
       // --- Combined Report --- 
       console.log('\n✅ Snapshot generation complete!');
       console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -562,6 +674,13 @@ export async function createRepoSnapshot(repoPath, options) {
         }
       }
 
+      // Security Report Section
+      if (stats.secretsRedacted > 0) {
+        console.log('\n🔐 Security:');
+        console.log('---------------------------------');
+        console.log(chalk.yellow(`   ⚠️  ${stats.secretsRedacted} secret(s) detected and redacted`));
+      }
+
       // Excluded/Skipped Files Section
       const hasExcludedContent = stats.excludedFiles > 0 || stats.binaryFiles > 0 || stats.oversizedFiles > 0 || stats.ignoredFiles > 0 || stats.errors.length > 0;
       if (hasExcludedContent) {

package/src/cli/commands/doctor.js

@@ -0,0 +1,60 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+
+/**
+ * Scans .eck directory for files containing [STUB] markers
+ */
+export async function runDoctor(repoPath = process.cwd()) {
+  const eckDir = path.join(repoPath, '.eck');
+  console.log(chalk.blue('🏥 Checking project health and manifest integrity...'));
+
+  try {
+    await fs.access(eckDir);
+  } catch {
+    console.log(chalk.yellow('⚠️  .eck directory not found. Nothing to check.'));
+    return;
+  }
+
+  const stubFiles = [];
+  const scannedFiles = [];
+
+  async function scan(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await scan(fullPath);
+      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json'))) {
+        scannedFiles.push(fullPath);
+        const content = await fs.readFile(fullPath, 'utf-8');
+        if (content.includes('[STUB:')) {
+          stubFiles.push({
+            path: path.relative(repoPath, fullPath),
+            type: 'STUB'
+          });
+        }
+      }
+    }
+  }
+
+  await scan(eckDir);
+
+  if (stubFiles.length === 0) {
+    console.log(chalk.green(`\n✅ All clear! Found ${scannedFiles.length} manifest files and no stubs.`));
+  } else {
+    console.log(chalk.red(`\n❌ Found ${stubFiles.length} files that need attention:`));
+    stubFiles.forEach(file => {
+      console.log(chalk.yellow(`   - ${file.path} `) + chalk.gray('(contains [STUB] marker)'));
+    });
+    console.log(chalk.cyan('\n💡 Tip: Instruct your Coder agent to "Finalize these stubs by analyzing the code".'));
+  }
+
+  // Cross-platform tree-sitter check
+  try {
+    const ts = await import('tree-sitter');
+    console.log(chalk.green('✅ tree-sitter: Installed and loadable.'));
+  } catch (e) {
+    console.log(chalk.yellow('ℹ️  tree-sitter: Not available (Skeleton mode will be limited for non-JS files).'));
+  }
+}

package/src/cli/commands/updateSnapshot.js

@@ -3,7 +3,7 @@ import path from 'path';
 import ora from 'ora';
 import { getGitAnchor, getChangedFiles, getGitDiffOutput } from '../../utils/gitUtils.js';
 import { loadSetupConfig } from '../../config.js';
-import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore } from '../../utils/fileUtils.js';
+import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore, generateTimestamp } from '../../utils/fileUtils.js';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -53,14 +53,14 @@ export async function updateSnapshot(repoPath, options) {
     const templatePath = path.join(__dirname, '../../templates/update-prompt.template.md');
     let header = await fs.readFile(templatePath, 'utf-8');
     header = header.replace('{{anchor}}', anchor.substring(0, 7))
-      .replace('{{timestamp}}', new Date().toISOString())
+      .replace('{{timestamp}}', new Date().toLocaleString())
       .replace('{{fileList}}', fileList.join('\n'));
 
     // Add Git Diff at the end for context
     const diffOutput = await getGitDiffOutput(repoPath, anchor);
     const diffSection = `\n--- GIT DIFF (For Context) ---\n\n\`\`\`diff\n${diffOutput}\n\`\`\``;
 
-    const outputFilename = `update_${new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-')}.md`;
+    const outputFilename = `update_${generateTimestamp()}.md`;
     const outputPath = path.join(repoPath, '.eck', 'snapshots', outputFilename);
 
     await fs.mkdir(path.dirname(outputPath), { recursive: true });

package/src/config.js

@@ -16,6 +16,10 @@ export async function loadSetupConfig() {
     const setupPath = path.join(__dirname, '..', 'setup.json');
     const setupContent = await fs.readFile(setupPath, 'utf-8');
     cachedConfig = JSON.parse(setupContent);
+
+    // Basic schema validation for critical fields
+    validateConfigSchema(cachedConfig);
+
     return cachedConfig;
   } catch (error) {
     console.error('Error loading setup.json:', error.message);
@@ -23,6 +27,46 @@ export async function loadSetupConfig() {
   }
 }
 
+/**
+ * Validates critical config fields and warns if missing or invalid
+ */
+function validateConfigSchema(config) {
+  const warnings = [];
+
+  // Validate fileFiltering section
+  if (!config.fileFiltering) {
+    warnings.push('Missing "fileFiltering" section');
+  } else {
+    if (!Array.isArray(config.fileFiltering.filesToIgnore)) {
+      warnings.push('"fileFiltering.filesToIgnore" must be an array');
+    }
+    if (!Array.isArray(config.fileFiltering.dirsToIgnore)) {
+      warnings.push('"fileFiltering.dirsToIgnore" must be an array');
+    }
+  }
+
+  // Validate aiInstructions section
+  if (!config.aiInstructions) {
+    warnings.push('Missing "aiInstructions" section');
+  }
+
+  // Legacy support
+  if (!config.filesToIgnore || !Array.isArray(config.filesToIgnore)) {
+    warnings.push('filesToIgnore missing or not an array - using defaults');
+    config.filesToIgnore = DEFAULT_CONFIG.filesToIgnore;
+  }
+  if (!config.dirsToIgnore || !Array.isArray(config.dirsToIgnore)) {
+    warnings.push('dirsToIgnore missing or not an array - using defaults');
+    config.dirsToIgnore = DEFAULT_CONFIG.dirsToIgnore;
+  }
+
+  if (warnings.length > 0) {
+    console.warn('\n⚠️ Config Validation Warnings:');
+    warnings.forEach(w => console.warn(`   - ${w}`));
+    console.warn('   (Falling back to defaults for missing values where possible)\n');
+  }
+}
+
 /**
  * Loads and merges all profiles (local-first).
  */