// Package intelligence provides context analysis and generation capabilities for the SLURP system.
//
// This package implements the AI-powered analysis engine that generates contextual understanding
// from filesystem content, code structure, and existing project knowledge. It integrates with
// RAG systems and uses role-specific analysis to create comprehensive context metadata.
//
// Key Features:
//   - Intelligent file content analysis and context generation
//   - Integration with RAG systems for enhanced context understanding
//   - Role-specific context insights and recommendations
//   - Project goal alignment assessment and tracking
//   - Pattern detection and context template application
//   - Multi-language code analysis and understanding
//
// Core Components:
//   - IntelligenceEngine: Main interface for context analysis and generation
//   - FileAnalyzer: Analyzes individual files for context extraction
//   - DirectoryAnalyzer: Analyzes directory structures and patterns
//   - PatternDetector: Identifies recurring patterns in codebases
//   - GoalAligner: Assesses alignment with project goals
//
// Integration Points:
//   - pkg/slurp/context: Uses context types for generated metadata
//   - pkg/slurp/temporal: Creates temporal context evolution records
//   - pkg/slurp/roles: Applies role-specific analysis and insights
//   - External RAG systems: Enhances context with knowledge retrieval
//   - Language servers: Integrates with existing language analysis
//
// Example Usage:
//
//	engine := intelligence.NewEngine(config, ragClient)
//	ctx := context.Background()
//	
//	// Analyze a file for context generation
//	contextNode, err := engine.AnalyzeFile(ctx, "/path/to/file.go", "developer")
//	if err != nil {
//	    log.Fatal(err)
//	}
//	
//	// Generate role-specific insights
//	insights, err := engine.GenerateRoleInsights(ctx, contextNode, "architect")
//	if err != nil {
//	    log.Fatal(err)
//	}
//	
//	fmt.Printf("Generated context: %s\n", contextNode.Summary)
//	fmt.Printf("Role insights: %v\n", insights)
//
// Leadership Integration:
// This package is designed to be used primarily by the elected CHORUS leader node,
// which has the responsibility for context generation across the cluster. The
// intelligence engine coordinates with the leader election system to ensure
// only authorized nodes perform context generation operations.
//
// Performance Considerations:
// - Concurrent analysis of multiple files with worker pools
// - Caching of analysis results to avoid repeated computation
// - Streaming analysis for large files to manage memory usage
// - Rate limiting for external RAG system integration
// - Prioritized processing based on file importance and frequency
//
// Quality Assurance:
// - Confidence scoring for all generated context
// - Validation against existing context for consistency
// - Feedback integration for continuous improvement
// - Role-specific quality thresholds and filtering
// - Pattern matching against known good examples
package intelligence