aiknowsys 0.6.0 → 0.7.0

package/lib/commands/audit.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import path from 'path';
+import ora from 'ora';
 import { createLogger } from '../logger.js';
+import { ErrorTemplates } from '../error-helpers.js';
 
 /**
  * Audit command - Finds common issues and pattern violations
@@ -26,42 +28,86 @@ export async function audit(options) {
   
   // Check if knowledge system exists
   if (!fs.existsSync(essentialsPath) && !fs.existsSync(agentsPath)) {
-    log.error('No knowledge system found in this directory');
-    log.dim('   Run: npx aiknowsys init');
-    log.blank();
-    throw new Error('No knowledge system found');
+    throw ErrorTemplates.noKnowledgeSystem();
+  }
+  
+  // Edge case: Check file sizes before reading
+  const filesToCheck = [
+    { path: essentialsPath, name: 'CODEBASE_ESSENTIALS.md' },
+    { path: agentsPath, name: 'AGENTS.md' },
+    { path: changelogPath, name: 'CODEBASE_CHANGELOG.md' }
+  ];
+  
+  for (const file of filesToCheck) {
+    if (fs.existsSync(file.path)) {
+      const stats = fs.statSync(file.path);
+      const fileSize = stats.size;
+      const fiftyMB = 50 * 1024 * 1024;
+      
+      // Edge case: File is empty
+      if (fileSize === 0) {
+        throw ErrorTemplates.emptyFile(file.name);
+      }
+      
+      // Edge case: File too large
+      if (fileSize > fiftyMB) {
+        throw ErrorTemplates.fileTooLarge(file.name, fileSize / 1024 / 1024);
+      }
+    }
   }
   
+  // Create spinner for progress (only if not silent)
+  const spinner = silent ? null : ora('Starting audit...').start();
+  
   // Audit 1: Check for duplicated validation matrix
-  log.white('🔍 Checking for duplication issues...');
+  if (spinner) {
+    spinner.text = 'Check 1/5: Checking for duplication issues...';
+  } else {
+    log.white('🔍 Checking for duplication issues...');
+  }
   
   if (fs.existsSync(essentialsPath) && fs.existsSync(agentsPath)) {
-    const essentialsContent = fs.readFileSync(essentialsPath, 'utf-8');
-    const agentsContent = fs.readFileSync(agentsPath, 'utf-8');
-    
-    // Look for validation matrix table in both files
-    const matrixTablePattern = /\|\s*Command\s*\|.*\|[\s\S]*?\|.*test.*\|/i;
-    const hasEssentialsMatrix = matrixTablePattern.test(essentialsContent);
-    const hasAgentsMatrix = matrixTablePattern.test(agentsContent);
-    
-    if (hasEssentialsMatrix && hasAgentsMatrix) {
-      log.warn('Validation matrix duplicated in both files');
+    try {
+      const essentialsContent = fs.readFileSync(essentialsPath, 'utf-8');
+      const agentsContent = fs.readFileSync(agentsPath, 'utf-8');
+      
+      // Look for validation matrix table in both files
+      const matrixTablePattern = /\|\s*Command\s*\|.*\|[\s\S]*?\|.*test.*\|/i;
+      const hasEssentialsMatrix = matrixTablePattern.test(essentialsContent);
+      const hasAgentsMatrix = matrixTablePattern.test(agentsContent);
+      
+      if (hasEssentialsMatrix && hasAgentsMatrix) {
+        log.warn('Validation matrix duplicated in both files');
+        issues.push({
+          type: 'warning',
+          category: 'DRY Violation',
+          message: 'Validation matrix appears in both ESSENTIALS and AGENTS',
+          fix: 'Run: npx aiknowsys sync'
+        });
+        warnings++;
+      } else if (hasEssentialsMatrix) {
+        log.log('  ✓ Validation matrix in ESSENTIALS only (correct)');
+      }
+    } catch (error) {
+      // Handle malformed or corrupted files gracefully
+      info++;
       issues.push({
-        type: 'warning',
-        category: 'DRY Violation',
-        message: 'Validation matrix appears in both ESSENTIALS and AGENTS',
-        fix: 'Run: npx aiknowsys sync'
+        type: 'info',
+        category: 'File Processing',
+        message: `Could not fully parse files: ${error.message}`,
+        fix: 'Check file encoding and markdown structure'
       });
-      warnings++;
-    } else if (hasEssentialsMatrix) {
-      log.log('  ✓ Validation matrix in ESSENTIALS only (correct)');
     }
   }
   
   log.blank();
   
   // Audit 2: Check for generic placeholder values
-  log.white('📝 Checking for placeholder quality...');
+  if (spinner) {
+    spinner.text = 'Check 2/5: Checking placeholder quality...';
+  } else {
+    log.white('📝 Checking for placeholder quality...');
+  }
   
   if (fs.existsSync(essentialsPath)) {
     const content = fs.readFileSync(essentialsPath, 'utf-8');
@@ -125,7 +171,11 @@ export async function audit(options) {
   log.blank();
   
   // Audit 3: Check validation matrix quality
-  log.white('✅ Checking validation matrix quality...');
+  if (spinner) {
+    spinner.text = 'Check 3/5: Checking validation matrix quality...';
+  } else {
+    log.white('✅ Checking validation matrix quality...');
+  }
   
   if (fs.existsSync(essentialsPath)) {
     const content = fs.readFileSync(essentialsPath, 'utf-8');
@@ -172,7 +222,11 @@ export async function audit(options) {
   log.blank();
   
   // Audit 4: Check changelog usage
-  log.white('📚 Checking changelog...');
+  if (spinner) {
+    spinner.text = 'Check 4/5: Checking changelog...';
+  } else {
+    log.white('📚 Checking changelog...');
+  }
   
   if (fs.existsSync(changelogPath)) {
     const content = fs.readFileSync(changelogPath, 'utf-8');
@@ -192,7 +246,11 @@ export async function audit(options) {
   log.blank();
   
   // Audit 5: Check .aiknowsys/ gitignore configuration
-  log.white('🔒 Checking .aiknowsys/ gitignore...');
+  if (spinner) {
+    spinner.text = 'Check 5/5: Checking .aiknowsys/ gitignore...';
+  } else {
+    log.white('🔒 Checking .aiknowsys/ gitignore...');
+  }
   
   const gitignorePath = path.join(targetDir, '.gitignore');
   const aiknowsysDir = path.join(targetDir, '.aiknowsys');
@@ -266,6 +324,9 @@ export async function audit(options) {
   
   log.blank();
   
+  // Stop spinner before summary
+  if (spinner) spinner.succeed('Audit complete');
+  
   // Summary
   log.section('Audit Summary', '📊');
   

package/lib/commands/check.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { createLogger } from '../logger.js';
+import { ErrorTemplates } from '../error-helpers.js';
 
 /**
  * Check command - Validates knowledge system setup
@@ -28,9 +29,36 @@ export async function check(options) {
   ];
   
   log.white('📁 Checking required files...');
+  const warnings = [];
+  
   for (const file of requiredFiles) {
     const filePath = path.join(targetDir, file.path);
     if (fs.existsSync(filePath)) {
+      // Check file size and content
+      const stats = fs.statSync(filePath);
+      const fileSize = stats.size;
+      
+      // Edge case: Empty file
+      if (fileSize === 0) {
+        log.log(`  ✗ ${file.name} - Empty file`);
+        checks.push({ name: file.name, status: 'fail', error: 'File is empty' });
+        failed++;
+        throw ErrorTemplates.emptyFile(file.path);
+      }
+      
+      // Edge case: Huge file (>5MB warning, >50MB error)
+      const fiveMB = 5 * 1024 * 1024;
+      const fiftyMB = 50 * 1024 * 1024;
+      
+      if (fileSize > fiftyMB) {
+        log.log(`  ✗ ${file.name} - File too large (${(fileSize / 1024 / 1024).toFixed(1)}MB)`);
+        checks.push({ name: file.name, status: 'fail', error: 'File size exceeds 50MB limit' });
+        failed++;
+        throw ErrorTemplates.fileTooLarge(file.path, fileSize / 1024 / 1024);
+      } else if (fileSize > fiveMB) {
+        warnings.push(`${file.name} is large (${(fileSize / 1024 / 1024).toFixed(1)}MB). Consider splitting content into multiple files.`);
+      }
+      
       log.log(`  ✓ ${file.name}`);
       checks.push({ name: file.name, status: 'pass' });
       passed++;
@@ -177,9 +205,10 @@ export async function check(options) {
   if (failed > 0) {
     log.log(`  ✗ Failed: ${failed}`);
   }
-  const warnings = checks.filter(c => c.status === 'warn').length;
-  if (warnings > 0) {
-    log.log(`  ⚠ Warnings: ${warnings}`);
+  const warningCount = checks.filter(c => c.status === 'warn').length;
+  if (warningCount > 0 || warnings.length > 0) {
+    log.log(`  ⚠ Warnings: ${warningCount + warnings.length}`);
+    warnings.forEach(w => log.warn(`  • ${w}`));
   }
   
   log.blank();
@@ -209,10 +238,13 @@ export async function check(options) {
   // Exit with appropriate code
   if (failed > 0) {
     log.error('Health check failed');
-    throw new Error(`Health check failed: ${failed} check(s) failed`);
-  } else if (warnings > 0) {
+    const failedList = checks.filter(c => c.status === 'fail').map(c => c.name);
+    throw ErrorTemplates.validationFailed(failed, failedList);
+  } else if (warningCount > 0 || warnings.length > 0) {
     log.warn('Health check passed with warnings');
+    return { checks, passed, failed, warnings }; // Return for programmatic use
   } else {
     log.success('Health check passed');
+    return { checks, passed, failed, warnings }; // Return for programmatic use
   }
 }

package/lib/commands/init/templates.js

@@ -4,7 +4,6 @@
 import fs from 'fs';
 import path from 'path';
 import ora from 'ora';
-import { createLogger } from '../../logger.js';
 import { getPackageDir, copyTemplate } from '../../utils.js';
 import { getProjectTypeName, getLanguageName, getFrameworkName, buildValidationMatrix, TEMPLATE_PATHS } from './index.js';
 

package/lib/commands/migrate.js

@@ -1,16 +1,18 @@
 import fs from 'fs';
 import path from 'path';
 import inquirer from 'inquirer';
+import ora from 'ora';
 import { createLogger } from '../logger.js';
 import { scan } from './scan.js';
 import { installAgents } from './install-agents.js';
 import { installSkills } from './install-skills.js';
-import { getPackageDir, copyTemplate, displayAIPrompt } from '../utils.js';
+import { getPackageDir, copyTemplate, displayAIPrompt, FileTracker } from '../utils.js';
 
 export async function migrate(options) {
   const targetDir = path.resolve(options.dir);
   const essentialsFile = options.essentials || 'CODEBASE_ESSENTIALS.md';
   const log = createLogger(false);
+  const tracker = new FileTracker();
   
   log.blank();
   log.header('Knowledge System Migration (Existing Project)', '🚀');
@@ -35,13 +37,23 @@ export async function migrate(options) {
     return;
   }
   
+  try {
+  
   // Step 1: Scan codebase
   log.blank();
   log.cyan('══════════════════════════════════════════');
   log.header('Step 1/5: Scanning codebase', '');
   log.cyan('══════════════════════════════════════════');
   
+  // Create single spinner for entire migration workflow (Steps 1-5)
+  // Reused across automated phases (skipped for Step 2's interactive prompts)
+  const spinner = ora('Scanning codebase...').start();
   const _findings = await scan({ dir: targetDir, output: 'CODEBASE_ESSENTIALS.draft.md' });
+  spinner.succeed('Codebase scan complete');
+  
+  // Track draft file for rollback if migration fails
+  const draftPath = path.join(targetDir, 'CODEBASE_ESSENTIALS.draft.md');
+  tracker.trackFile(draftPath);
   
   // Step 2: Review draft
   log.blank();
@@ -68,18 +80,18 @@ export async function migrate(options) {
   }]);
   
   const essentialsPath = path.join(targetDir, essentialsFile);
-  const draftPath = path.join(targetDir, 'CODEBASE_ESSENTIALS.draft.md');
   
   if (!reviewed && !fs.existsSync(essentialsPath)) {
     const { action } = await inquirer.prompt([{
-      type: 'list',
+      type: 'rawlist',
       name: 'action',
       message: `${essentialsFile} not found. What would you like to do?`,
       choices: [
         { name: 'Rename draft file now and continue', value: 'rename' },
         { name: 'Continue anyway (not recommended)', value: 'continue' },
         { name: 'Exit and complete the file first', value: 'exit' }
-      ]
+      ],
+      default: 1
     }]);
     
     if (action === 'exit') {
@@ -87,8 +99,9 @@ export async function migrate(options) {
       return;
     }
     
-    if (action === 'rename' && fs.existsSync(draftPath)) {
-      fs.renameSync(draftPath, essentialsPath);
+    const draftFilePath = path.join(targetDir, 'CODEBASE_ESSENTIALS.draft.md');
+    if (action === 'rename' && fs.existsSync(draftFilePath)) {
+      fs.renameSync(draftFilePath, essentialsPath);
       log.success('✅ Renamed to CODEBASE_ESSENTIALS.md');
     }
   }
@@ -99,6 +112,7 @@ export async function migrate(options) {
   log.header('Step 3/5: Creating AGENTS.md', '');
   log.cyan('══════════════════════════════════════════');
   
+  spinner.start('Creating AGENTS.md...');
   const agentsPath = path.join(targetDir, 'AGENTS.md');
   if (!fs.existsSync(agentsPath)) {
     const packageDir = getPackageDir();
@@ -106,8 +120,11 @@ export async function migrate(options) {
       path.join(packageDir, 'templates', 'AGENTS.template.md'),
       agentsPath
     );
+    tracker.trackFile(agentsPath);
+    spinner.succeed('AGENTS.md created');
     log.success('✅ AGENTS.md created (customize validation matrix as needed)');
   } else {
+    spinner.info('AGENTS.md already exists');
     log.dim('⏭️  AGENTS.md already exists, skipping');
   }
   
@@ -117,7 +134,9 @@ export async function migrate(options) {
   log.header('Step 4/5: Installing custom agents', '');
   log.cyan('══════════════════════════════════════════');
   
+  spinner.start('Installing custom agents...');
   await installAgents({ dir: targetDir, essentials: essentialsFile });
+  spinner.succeed('Custom agents installed');
   
   // Step 5: Install skills
   log.blank();
@@ -125,7 +144,9 @@ export async function migrate(options) {
   log.header('Step 5/5: Installing universal skills', '');
   log.cyan('══════════════════════════════════════════');
   
+  spinner.start('Installing universal skills...');
   await installSkills({ dir: targetDir });
+  spinner.succeed('Universal skills installed');
   
   // Initialize changelog
   const changelogPath = path.join(targetDir, 'CODEBASE_CHANGELOG.md');
@@ -140,6 +161,7 @@ export async function migrate(options) {
         '{{DATE}}': new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
       }
     );
+    tracker.trackFile(changelogPath);
     log.success('✅ CODEBASE_CHANGELOG.md initialized');
   }
   
@@ -172,4 +194,9 @@ export async function migrate(options) {
     '5. Explaining architecture decisions',
     'Make it project-specific, not a template!"'
   ]);
+  } catch (error) {
+    log.error(`Migration failed: ${error.message}`);
+    await tracker.rollback(log);
+    throw error;
+  }
 }

package/lib/commands/scan.js

@@ -225,10 +225,11 @@ export async function scan(options) {
     
     // Scan for common pattern directories
     const commonDirs = ['src', 'lib', 'server', 'backend', 'api', 'app'];
+    let filesScanned = 0;
     for (const dir of commonDirs) {
       const dirPath = path.join(targetDir, dir);
       if (fs.existsSync(dirPath)) {
-        scanForPatterns(dirPath, findings);
+        filesScanned = scanForPatterns(dirPath, findings, spinner, filesScanned);
       }
     }
     
@@ -270,7 +271,7 @@ export async function scan(options) {
     log.log('\x1b[33m\x1b[1m📝 Next Steps:\x1b[0m');
     log.white(`   1. Review and complete TODO sections in ${outputFile}`);
     log.white('   2. Rename to CODEBASE_ESSENTIALS.md when ready');
-    log.white(`   3. Run: `);
+    log.white('   3. Run: ');
     log.cyan('      npx aiknowsys install-agents');
     log.blank();
     
@@ -294,9 +295,9 @@ export async function scan(options) {
   }
 }
 
-function scanForPatterns(dir, findings, depth = 0) {
+function scanForPatterns(dir, findings, spinner = null, filesScanned = 0, depth = 0) {
   // Limit recursion depth to avoid performance issues
-  if (depth > 2) return;
+  if (depth > 2) return filesScanned;
   
   try {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -316,8 +317,15 @@ function scanForPatterns(dir, findings, depth = 0) {
         if (entry.name === 'middleware' || entry.name === 'auth') findings.patterns.hasAuthMiddleware = true;
         
         // Recurse into subdirectories
-        scanForPatterns(fullPath, findings, depth + 1);
+        filesScanned = scanForPatterns(fullPath, findings, spinner, filesScanned, depth + 1);
       } else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.ts'))) {
+        filesScanned++;
+        
+        // Update spinner text every 50 files for better performance
+        if (spinner && filesScanned % 50 === 0) {
+          spinner.text = `Analyzing codebase... (${filesScanned} files scanned)`;
+        }
+        
         // Quick scan of file content for patterns
         try {
           const content = fs.readFileSync(fullPath, 'utf-8');
@@ -343,6 +351,8 @@ function scanForPatterns(dir, findings, depth = 0) {
   } catch (_e) {
     // Skip directories we can't read
   }
+  
+  return filesScanned;
 }
 
 function generateEssentialsDraft(findings) {

package/lib/commands/sync.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import ora from 'ora';
 import { createLogger } from '../logger.js';
+import { ErrorTemplates } from '../error-helpers.js';
 
 /**
  * Sync command - Syncs AGENTS.md validation reference with CODEBASE_ESSENTIALS.md
@@ -22,15 +23,11 @@ export async function sync(options) {
   
   // Check files exist
   if (!fs.existsSync(essentialsPath)) {
-    log.error(`${essentialsFile} not found`);
-    log.dim('   Run: npx aiknowsys init');
-    throw new Error(`${essentialsFile} not found`);
+    throw ErrorTemplates.fileNotFound(essentialsFile, ['npx aiknowsys init']);
   }
   
   if (!fs.existsSync(agentsPath)) {
-    log.error('AGENTS.md not found');
-    log.dim('   Run: npx aiknowsys init');
-    throw new Error('AGENTS.md not found');
+    throw ErrorTemplates.fileNotFound('AGENTS.md', ['npx aiknowsys init']);
   }
   
   const spinner = silent ? null : ora('Checking validation matrix...').start();
@@ -42,9 +39,7 @@ export async function sync(options) {
   
   if (!hasValidationMatrix) {
     if (spinner) spinner.fail('Validation matrix not found in CODEBASE_ESSENTIALS.md');
-    log.blank();
-    log.info('Add a Validation Matrix section to CODEBASE_ESSENTIALS.md');
-    throw new Error('Validation matrix not found in CODEBASE_ESSENTIALS.md');
+    throw ErrorTemplates.missingSection('Validation Matrix', essentialsFile);
   }
   
   if (spinner) spinner.text = 'Reading AGENTS.md...';

package/lib/error-helpers.js

@@ -0,0 +1,178 @@
+/**
+ * Error handling utilities for AIKnowSys
+ * Provides structured errors with helpful suggestions and documentation links
+ */
+
+/**
+ * AIKnowSys structured error with helpful suggestions
+ * 
+ * @example
+ * throw new AIKnowSysError(
+ *   'CODEBASE_ESSENTIALS.md not found',
+ *   'Create it by running:\n  aiknowsys scan  (from existing code)\n  aiknowsys init   (from scratch)',
+ *   'https://github.com/arpa73/AIKnowSys#getting-started'
+ * );
+ */
+export class AIKnowSysError extends Error {
+  /**
+   * @param {string} message - What went wrong
+   * @param {string} suggestion - How to fix it
+   * @param {string} learnMore - URL to documentation (optional)
+   */
+  constructor(message, suggestion, learnMore = null) {
+    super(message);
+    this.suggestion = suggestion;
+    this.learnMore = learnMore;
+    this.name = 'AIKnowSysError';
+    
+    // Maintain proper stack trace (V8 engine)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AIKnowSysError);
+    }
+  }
+  
+  /**
+   * Format error with logger for consistent display
+   * @param {object} log - Logger instance with error(), info() methods
+   */
+  format(log) {
+    log.error(this.message);
+    log.blank();
+    
+    if (this.suggestion) {
+      log.info('💡 How to fix:');
+      // Split multi-line suggestions and indent them
+      const lines = this.suggestion.split('\n');
+      lines.forEach(line => {
+        if (line.trim()) {
+          log.white(`   ${line}`);
+        } else {
+          log.blank();
+        }
+      });
+      log.blank();
+    }
+    
+    if (this.learnMore) {
+      log.cyan(`📚 Learn more: ${this.learnMore}`);
+      log.blank();
+    }
+  }
+  
+  /**
+   * Get plain text version (for silent mode or testing)
+   * @returns {string} Formatted error message
+   */
+  toPlainText() {
+    let text = `✗ ${this.message}\n`;
+    
+    if (this.suggestion) {
+      text += `\n💡 How to fix:\n${this.suggestion}\n`;
+    }
+    
+    if (this.learnMore) {
+      text += `\n📚 Learn more: ${this.learnMore}\n`;
+    }
+    
+    return text;
+  }
+}
+
+/**
+ * Common error templates for consistency
+ */
+export const ErrorTemplates = {
+  /**
+   * File not found error
+   * @param {string} filename - Name of missing file
+   * @param {string[]} suggestions - Array of command suggestions
+   * @returns {AIKnowSysError}
+   */
+  fileNotFound(filename, suggestions = []) {
+    const defaultSuggestions = [
+      'aiknowsys scan    # Generate from existing codebase',
+      'aiknowsys init    # Start from scratch',
+    ];
+    
+    const suggestionText = (suggestions.length > 0 ? suggestions : defaultSuggestions)
+      .map((s, i) => `${i + 1}. ${s}`)
+      .join('\n');
+    
+    return new AIKnowSysError(
+      `${filename} not found`,
+      `This file is required for AIKnowSys to work. Create it by running:\n\n${suggestionText}`,
+      'https://github.com/arpa73/AIKnowSys#getting-started'
+    );
+  },
+  
+  /**
+   * Empty file error
+   * @param {string} filename - Name of empty file
+   * @returns {AIKnowSysError}
+   */
+  emptyFile(filename) {
+    return new AIKnowSysError(
+      `${filename} is empty or has no content`,
+      'Generate content by running:\n\n1. aiknowsys scan    # Analyze existing codebase\n2. Fill in manually  # Copy template and customize',
+      'https://github.com/arpa73/AIKnowSys#scanning-existing-projects'
+    );
+  },
+  
+  /**
+   * File too large error
+   * @param {string} filename - Name of large file
+   * @param {number} sizeMB - File size in megabytes
+   * @returns {AIKnowSysError}
+   */
+  fileTooLarge(filename, sizeMB) {
+    return new AIKnowSysError(
+      `${filename} is too large (${sizeMB.toFixed(1)}MB)`,
+      'Files larger than 50MB can cause performance issues.\n\nConsider:\n1. Split content into multiple files\n2. Move detailed examples to separate docs\n3. Use references/links instead of inline content',
+      'https://github.com/arpa73/AIKnowSys/wiki/Best-Practices#keeping-files-lean'
+    );
+  },
+  
+  /**
+   * Missing section error
+   * @param {string} section - Name of missing section
+   * @param {string} filename - File that should contain the section
+   * @returns {AIKnowSysError}
+   */
+  missingSection(section, filename) {
+    return new AIKnowSysError(
+      `Required section "${section}" not found in ${filename}`,
+      `Add this section to your ${filename}:\n\n1. Copy from template:\n   cp node_modules/aiknowsys/templates/${filename.replace('.md', '.template.md')} ./${filename}\n\n2. Or update to latest:\n   aiknowsys update --templates`,
+      'https://github.com/arpa73/AIKnowSys#codebase-essentials-structure'
+    );
+  },
+  
+  /**
+   * Validation failed error
+   * @param {number} failedCount - Number of failed checks
+   * @param {string[]} failures - Array of failure descriptions
+   * @returns {AIKnowSysError}
+   */
+  validationFailed(failedCount, failures = []) {
+    const failureList = failures.length > 0
+      ? failures.map((f, i) => `${i + 1}. ${f}`).join('\n')
+      : 'See details above';
+    
+    return new AIKnowSysError(
+      `Health check failed: ${failedCount} check(s) failed`,
+      `Fix the following issues:\n\n${failureList}\n\nThen run:\n  aiknowsys check    # Verify fixes`,
+      'https://github.com/arpa73/AIKnowSys#health-checks'
+    );
+  },
+  
+  /**
+   * No knowledge system found error
+   * @returns {AIKnowSysError}
+   */
+  noKnowledgeSystem() {
+    return new AIKnowSysError(
+      'No knowledge system found in this directory',
+      'Initialize AIKnowSys by running:\n\n1. aiknowsys init      # Interactive setup\n2. aiknowsys init --yes # Quick setup with defaults\n3. aiknowsys migrate    # Migrate existing project',
+      'https://github.com/arpa73/AIKnowSys#quick-start'
+    );
+  }
+};

package/lib/sanitize.js

@@ -38,6 +38,22 @@ export function sanitizeProjectName(name) {
     errors.push('Project name can only contain letters, numbers, hyphens, underscores, and dots');
   }
   
+  // Check for emoji and special Unicode characters
+  // Emoji range: U+1F300 to U+1F9FF (and others)
+  if (/[\u{1F300}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}]/u.test(trimmed)) {
+    errors.push('Project name cannot contain emoji or special Unicode characters');
+  }
+  
+  // Check for npm reserved names
+  const reservedNames = [
+    'node_modules', 'favicon.ico', 'node', 'npm', 'package', 'readme',
+    'license', 'changelog', 'test', 'tests', 'example', 'examples'
+  ];
+  const lowercaseName = trimmed.toLowerCase().replace(/^@[^/]+\//, ''); // Remove scope
+  if (reservedNames.includes(lowercaseName)) {
+    errors.push(`Project name '${lowercaseName}' is reserved by npm`);
+  }
+  
   // Check for leading/trailing special characters
   if (/^[._-]/.test(trimmed)) {
     errors.push('Project name cannot start with a dot, hyphen, or underscore');
@@ -198,7 +214,7 @@ export function validatePathTraversal(basePath, userPath) {
   }
   
   // Normalize paths to prevent traversal
-  const normalizedBase = basePath.replace(/\\/g, '/').replace(/\/+$/, '');
+  const _normalizedBase = basePath.replace(/\\/g, '/').replace(/\/+$/, '');
   const normalizedUser = userPath.replace(/\\/g, '/');
   
   // Check for absolute paths (should be relative to base)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiknowsys",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AI-Powered Development Workflow for Consistent, High-Quality Code",
   "keywords": [
     "ai",

package/templates/AGENTS.template.md

@@ -258,36 +258,7 @@ Follow patterns from CODEBASE_ESSENTIALS.md and the skill you read.
 2. Use skill format with clear trigger words
 3. Document the pattern for future reuse
 
-**Example:**
-```markdown
-# Learned Skill: Django Query Optimization Pattern
-
-**Pattern Type:** project_specific  
-**Created:** {{DATE}}  
-**Trigger Words:** "slow query", "n+1 problem", "django performance"
-
-## When to Use
-Use when encountering slow Django queries with related objects.
-
-## Pattern
-Always use select_related() for foreign keys and prefetch_related() for many-to-many.
-
-\```python
-# ❌ N+1 query problem
-users = User.objects.all()
-for user in users:
-    print(user.profile.bio)  # Query per user!
-
-# ✅ Optimized with select_related
-users = User.objects.select_related('profile').all()
-for user in users:
-    print(user.profile.bio)  # Single query!
-\```
-
-## Related
-- Django ORM documentation
-- Performance monitoring with django-debug-toolbar
-```
+**See `.github/skills/skill-creator/SKILL.md` for detailed format and examples.**
 
 **Pattern Types:**
 - `error_resolution` - How specific errors were fixed
@@ -360,100 +331,6 @@ This project uses Developer + Architect agents for automated code review.
 
 ---
 
-## ✅ Pre-Commit Validation Checklist
-
-**Run this checklist BEFORE every commit. Copy-paste into terminal:**
-
-### Quick Check (1 minute)
-```bash
-# 1. Validation Matrix commands
-{{VALIDATION_CMD_1}}  # e.g., npm test
-{{VALIDATION_CMD_2}}  # e.g., npm run lint
-
-# 2. No debug code
-grep -r "console.log\|debugger\|TODO:" src/ || echo "✓ No debug code"
-
-# 3. No secrets
-grep -r "password\|api_key\|secret" . --exclude-dir={node_modules,.git} || echo "✓ No secrets"
-```
-
-### Full Check (5 minutes)
-```bash
-# Run all validation commands from matrix
-{{ALL_VALIDATION_COMMANDS}}
-
-# Additional checks
-git status                          # No untracked files
-git diff                            # Review changes
-grep "{{" {{TEMPLATE_FILES}}        # No unfilled placeholders
-```
-
-### Before Push
-```bash
-# Final validation
-{{VALIDATION_CMD_1}}
-
-# Check commits
-git log origin/main..HEAD           # Review commits
-
-# Push
-git push
-```
-
----
-
-## 🔍 Troubleshooting Validation Failures
-
-### Tests Failing
-1. Read error message carefully
-2. Check CODEBASE_ESSENTIALS.md for test patterns
-3. Review "Common Gotchas" section
-4. Run single failing test: `{{SINGLE_TEST_CMD}}`
-5. Check if pattern violated (Critical Invariants)
-
-### Linting Errors
-1. Auto-fix if possible: `{{AUTO_FIX_CMD}}`
-2. Review Core Patterns for style rules
-3. Don't disable rules - fix the code
-4. If rule is wrong, update ESSENTIALS first
-
-### Build Errors
-1. Check dependency versions (Technology Stack section)
-2. Clear cache: `{{CLEAR_CACHE_CMD}}`
-3. Rebuild from scratch: `{{CLEAN_BUILD_CMD}}`
-4. Check environment variables
-
----
-
-## 📝 Customization Instructions
-
-**This is a template file. To customize:**
-
-1. **{{SKILL_MAPPING}}** - Add your project's skill trigger words
-   ```markdown
-   | "refactor", "clean up" | code-refactoring | Test-driven refactoring |
-   | "update deps" | dependency-updates | Safe dependency updates |
-   | "write tests", "TDD", "test first" | tdd-workflow | Test-driven development |
-   ```
-
-2. **Validation Checklist Placeholders:**
-   - `{{VALIDATION_CMD_1}}` → Your primary test command (e.g., `npm test`)
-   - `{{VALIDATION_CMD_2}}` → Your lint command (e.g., `npm run lint`)
-   - `{{ALL_VALIDATION_COMMANDS}}` → All commands from validation matrix in ESSENTIALS
-   - `{{TEMPLATE_FILES}}` → Files to check for placeholders
-   - `{{SINGLE_TEST_CMD}}` → How to run one test (e.g., `npm test -- file.test.js`)
-   - `{{AUTO_FIX_CMD}}` → Auto-fix linting (e.g., `npm run lint:fix`)
-   - `{{CLEAR_CACHE_CMD}}` → Clear build cache
-   - `{{CLEAN_BUILD_CMD}}` → Clean rebuild command
-
-3. **Add project-specific sections** as needed
-
-4. **Remove placeholder text** and instructions
-
-**Note:** Validation Matrix is in CODEBASE_ESSENTIALS.md - no need to duplicate it here.
-
----
-
 *This file helps AI agents follow a consistent workflow: Read → Plan → Implement → Validate → Document → Confirm*
 
 *Part of aiknowsys. See [README](README.md) and [SETUP_GUIDE.md](SETUP_GUIDE.md) for full documentation.*

package/templates/agents/architect.agent.template.md

@@ -110,6 +110,44 @@ To ensure your review feedback is preserved and actionable:
    - Developer deletes PENDING_REVIEW.md after addressing issues
    - Session file gets brief completion status (not full review text)
 
+### Documentation Location Guidance (Read Before Reviewing!):
+
+When recommending where to document patterns during your review, use this decision framework:
+
+**Document in {{ESSENTIALS_FILE}} when:**
+- ✅ **Critical Invariants**: Cannot be violated (ES modules only, no globals, etc.)
+- ✅ **Core Patterns**: Used in EVERY file of that type (Logger, FileTracker, etc.)
+- ✅ **Architecture Decisions**: Technology choices (Node 20+, framework selections, etc.)
+- ✅ **Universal Rules**: Applies project-wide (KISS, DRY, test structure, etc.)
+- ⚠️ **Size check**: ESSENTIALS getting large (>350 lines)? Consider moving to learned/
+
+**Document in `.aiknowsys/learned/` when:**
+- ✅ **Project-Specific Patterns**: Emerged from practice (not planned upfront)
+- ✅ **Problem-Solution Pairs**: Recurring error with consistent fix
+- ✅ **Workarounds**: Library/framework-specific solutions
+- ✅ **Advanced Techniques**: Optional patterns that improve quality but aren't mandatory
+- ✅ **Domain Knowledge**: Business logic patterns, API conventions, etc.
+
+**Reasoning:**
+- ESSENTIALS = "What AI MUST know before any change" (single source of truth)
+- Learned = "What AI SHOULD know for this specific context" (discoverable via triggers)
+- Keep ESSENTIALS lean (<350 lines ideal) so AI reads it every session
+- Learned skills can be detailed without bloating core docs
+
+**How to recommend:**
+```markdown
+**Recommendation:** Document this as a learned skill.
+
+**Reasoning:** 
+- Pattern emerged from [context] implementation (not core architecture)
+- [X] distinct patterns discovered through practice
+- Optional technique that improves [aspect] but not mandatory
+- {{ESSENTIALS_FILE}} already at [X] lines (over ideal 350)
+- Fits Pattern Extraction Protocol in AGENTS.md
+
+**Action:** Create `.aiknowsys/learned/pattern-name.md` using skill format.
+```
+
 ### Additional Reminders to Developer:
 After completing your review, remind the developer to:
 - **Read PENDING_REVIEW.md:** "Detailed review written to `.aiknowsys/PENDING_REVIEW.md`"

package/templates/skills/validation-troubleshooting/SKILL.md

@@ -0,0 +1,486 @@
+---
+name: validation-troubleshooting
+description: Universal troubleshooting guide for validation failures (tests, linting, builds). Use when tests fail, validation commands error, or build breaks. Framework-agnostic debugging strategies for common development workflow issues.
+---
+
+# Validation Troubleshooting Skill
+
+Step-by-step debugging guide for when validation commands fail.
+
+## When to Use This Skill
+
+Use when:
+- Tests fail after making changes
+- Validation commands from matrix error
+- Build/compilation fails
+- Linting errors appear
+- Type checking fails
+- User mentions: "tests failing", "validation error", "build broken", "lint error"
+
+**Trigger words:** "test fail", "validation fail", "build error", "lint error", "type error", "won't compile"
+
+---
+
+## 1. Test Failures
+
+### Step 1: Read the Error Message Carefully
+
+**DON'T:**
+- ❌ Immediately modify code
+- ❌ Delete failing tests
+- ❌ Disable test runner
+
+**DO:**
+- ✅ Read full error output
+- ✅ Note exact line number and file
+- ✅ Identify what was expected vs actual
+
+### Step 2: Isolate the Failure
+
+Run only the failing test:
+
+```bash
+# Node.js
+npm test -- path/to/test.test.js
+
+# Python
+pytest path/to/test.py::test_name -v
+
+# Jest
+npm test -- --testNamePattern="test name"
+
+# Vitest
+npx vitest path/to/test.test.ts
+
+# Go
+go test -run TestName ./...
+
+# Rust
+cargo test test_name
+```
+
+### Step 3: Check Test Expectations
+
+**Common issues:**
+- Test expects old behavior (need to update test)
+- Implementation is wrong (fix code)
+- Test setup/mocking is incorrect
+- Environment/config mismatch
+
+**Questions to ask:**
+1. Is the test expectation still valid?
+2. Did I change behavior the test depends on?
+3. Are mocks/fixtures up to date?
+4. Does the test match CODEBASE_ESSENTIALS.md patterns?
+
+### Step 4: Debug the Test
+
+**Add logging:**
+```javascript
+// JavaScript/TypeScript
+console.log('Actual value:', result);
+console.log('Expected:', expected);
+
+// Python
+print(f"Actual: {result}, Expected: {expected}")
+
+// Rust
+println!("Actual: {:?}, Expected: {:?}", result, expected);
+```
+
+**Run in debug mode:**
+```bash
+# Node.js
+node --inspect-brk node_modules/.bin/jest --runInBand
+
+# Python
+python -m pdb -m pytest path/to/test.py
+
+# Rust
+rust-gdb target/debug/test_binary
+```
+
+### Step 5: Fix and Validate
+
+1. Fix the issue (code or test)
+2. Run the single test again - should pass
+3. Run full test suite - all should pass
+4. Commit with clear message explaining the fix
+
+**Never claim done without running full test suite!**
+
+---
+
+## 2. Linting Errors
+
+### Step 1: Identify Error Type
+
+**Syntax errors:**
+```
+Parsing error: Unexpected token
+Missing semicolon
+Unexpected identifier
+```
+→ **Fix:** Correct syntax immediately
+
+**Style violations:**
+```
+'variable' is assigned but never used
+Missing trailing comma
+Prefer const over let
+```
+→ **Fix:** Address or justify
+
+**Security issues:**
+```
+Detected eval usage
+Unsafe regex
+XSS vulnerability
+```
+→ **Fix:** MUST fix, don't disable
+
+### Step 2: Auto-Fix When Possible
+
+```bash
+# ESLint
+npm run lint:fix
+
+# Prettier
+npm run format
+
+# Black (Python)
+black .
+
+# Rustfmt
+cargo fmt
+
+# Go
+go fmt ./...
+```
+
+### Step 3: Manual Fixes
+
+**Read CODEBASE_ESSENTIALS.md for style rules:**
+- Check "Code Patterns" section
+- Verify naming conventions
+- Review import ordering
+
+**DON'T disable rules without justification:**
+```javascript
+// ❌ BAD - Disabling without reason
+// eslint-disable-next-line no-console
+console.log(data);
+
+// ✅ GOOD - Justified exception
+// eslint-disable-next-line no-console -- Debugging production issue #123
+console.log(data);
+```
+
+### Step 4: Update Rules If Wrong
+
+If rule conflicts with project patterns:
+1. Discuss with team/review ESSENTIALS
+2. Update linting config
+3. Document change in CODEBASE_CHANGELOG.md
+4. Update CODEBASE_ESSENTIALS.md if pattern changed
+
+---
+
+## 3. Build/Compilation Errors
+
+### Step 1: Check Error Category
+
+**Dependency errors:**
+```
+Cannot find module 'package-name'
+Module not found
+Package not installed
+```
+→ **Fix:** Install dependencies
+
+**Type errors:**
+```
+Type 'string' is not assignable to type 'number'
+Property 'x' does not exist on type 'Y'
+```
+→ **Fix:** Correct types or update type definitions
+
+**Configuration errors:**
+```
+Invalid configuration object
+Missing environment variable
+Unknown compiler option
+```
+→ **Fix:** Check config files
+
+### Step 2: Clean Build
+
+```bash
+# JavaScript/TypeScript
+rm -rf node_modules dist .cache
+npm install
+npm run build
+
+# Python
+rm -rf __pycache__ .pytest_cache dist
+pip install -r requirements.txt
+
+# Rust
+cargo clean
+cargo build
+
+# Go
+go clean -cache
+go build
+```
+
+### Step 3: Check Environment
+
+**Verify versions match CODEBASE_ESSENTIALS.md:**
+```bash
+# Check Node.js version
+node --version
+
+# Check Python version
+python --version
+
+# Check Rust version
+rustc --version
+
+# Check Go version
+go version
+```
+
+**Check environment variables:**
+```bash
+# List all env vars
+printenv
+
+# Check specific required vars
+echo $NODE_ENV
+echo $DATABASE_URL
+```
+
+### Step 4: Incremental Debugging
+
+1. Comment out recent changes
+2. Build incrementally
+3. Identify breaking change
+4. Fix root cause
+5. Uncomment and rebuild
+
+---
+
+## 4. Type Checking Errors
+
+### Common TypeScript Issues
+
+**Missing type definitions:**
+```bash
+npm install --save-dev @types/package-name
+```
+
+**Type mismatch:**
+```typescript
+// ❌ Wrong
+const id: number = "123";
+
+// ✅ Fix - convert type
+const id: number = parseInt("123", 10);
+
+// ✅ Or - fix type annotation
+const id: string = "123";
+```
+
+**Null/undefined issues:**
+```typescript
+// ❌ Unsafe
+const name = user.name;
+
+// ✅ Safe - optional chaining
+const name = user?.name;
+
+// ✅ Safe - nullish coalescing
+const name = user?.name ?? 'Unknown';
+```
+
+### Common Python Type Issues
+
+**mypy errors:**
+```bash
+# Run mypy
+mypy src/
+
+# Ignore specific line (rarely)
+result = something()  # type: ignore[attr-defined]
+```
+
+---
+
+## 5. Validation Matrix Command Failures
+
+### Strategy: Work Through Matrix Systematically
+
+**From CODEBASE_ESSENTIALS.md validation matrix:**
+
+```markdown
+| Command | Purpose | Expected |
+|---------|---------|----------|
+| npm test | Run tests | All pass |
+| npm run lint | Check style | No errors |
+| npm run build | Compile | No errors |
+```
+
+**Run each command:**
+1. If passes → ✅ Move to next
+2. If fails → 🔴 Debug using sections above
+3. Don't move forward until current command passes
+
+### Example Debugging Session
+
+```bash
+# 1. Run tests
+npm test
+# ❌ FAIL - 2 tests failing
+
+# 2. Isolate failure
+npm test -- auth.test.js
+# Read error, fix issue
+
+# 3. Verify fix
+npm test
+# ✅ PASS - All tests green
+
+# 4. Continue to next validation
+npm run lint
+# ✅ PASS - No issues
+
+# 5. Final check
+npm run build
+# ✅ PASS - Build successful
+```
+
+**Rule: Fix failures in order, don't skip ahead!**
+
+---
+
+## 6. Common Patterns and Solutions
+
+### Pattern: "Works on my machine"
+
+**Cause:** Environment differences
+
+**Solutions:**
+1. Check Node.js/Python/Rust version matches team
+2. Verify environment variables set correctly
+3. Clear caches and reinstall dependencies
+4. Check for OS-specific issues (Windows vs Unix paths)
+5. Use Docker/containers for consistency
+
+### Pattern: "Test passes locally, fails in CI"
+
+**Cause:** CI environment differences
+
+**Solutions:**
+1. Check CI logs carefully
+2. Verify CI environment variables
+3. Check for timing issues (add proper waits)
+4. Ensure deterministic test data
+5. Check for missing CI dependencies
+
+### Pattern: "Intermittent test failures"
+
+**Cause:** Non-deterministic tests
+
+**Solutions:**
+1. Remove time-dependent logic
+2. Fix race conditions
+3. Mock random/date functions
+4. Ensure proper cleanup between tests
+5. Avoid shared state
+
+### Pattern: "Everything broke after dependency update"
+
+**Cause:** Breaking changes in dependency
+
+**Solutions:**
+1. Check dependency changelog
+2. Revert to previous version temporarily
+3. Read migration guide
+4. Update code to new API
+5. Consider alternative package
+
+---
+
+## Workflow Checklist
+
+When validation fails:
+
+- [ ] **Read error message** - Don't guess
+- [ ] **Check CODEBASE_ESSENTIALS.md** - Verify patterns
+- [ ] **Isolate the issue** - Run single test/command
+- [ ] **Debug systematically** - Use tools, not trial-and-error
+- [ ] **Fix root cause** - Not just symptoms
+- [ ] **Verify fix** - Run full validation matrix
+- [ ] **Document if needed** - Update docs if pattern unclear
+- [ ] **Commit with context** - Explain what broke and why
+
+---
+
+## Never Do These
+
+❌ **Delete tests to make them pass**
+- Tests found a real issue
+- Fix the code, not the test
+
+❌ **Disable linting rules without justification**
+- Rules exist for a reason
+- Discuss with team first
+
+❌ **Skip validation steps**
+- "It probably works" is not good enough
+- Run full matrix before claiming done
+
+❌ **Commit broken code "to fix later"**
+- Breaks team workflow
+- Creates technical debt
+
+❌ **Change multiple things at once**
+- Can't identify root cause
+- Fix one thing, validate, then next
+
+---
+
+## Quick Reference
+
+### Emergency Triage
+
+```bash
+# 1. What broke?
+git diff  # Review recent changes
+
+# 2. When did it break?
+git log --oneline -10  # Recent commits
+
+# 3. Revert if needed
+git revert HEAD  # Undo last commit safely
+
+# 4. Isolate and fix
+# Use sections above based on error type
+
+# 5. Validate before moving on
+npm test && npm run lint && npm run build
+```
+
+### Getting Unstuck
+
+If stuck for >15 minutes:
+1. Read error message again (slowly)
+2. Check CODEBASE_ESSENTIALS.md for relevant pattern
+3. Search project for similar code that works
+4. Check dependency documentation
+5. Ask for help (provide full error message)
+
+---
+
+*Framework-agnostic troubleshooting - adapt commands to your project's tech stack.*