octocode-mcp 2.0.0 → 2.2.0

package/build/index.js

@@ -22,6 +22,8 @@ const TOOL_NAMES = {
     GITHUB_GET_FILE_CONTENT: 'github_get_file_content',
     // GitHub Users API (/user/*)
     GITHUB_GET_USER_ORGS: 'github_get_user_organizations',
+    // System & API Status
+    API_STATUS_CHECK: 'api_status_check',
     // npm Registry API - Comprehensive
     NPM_SEARCH_PACKAGES: 'npm_search_packages',
     NPM_GET_PACKAGE: 'npm_get_package',
@@ -40,222 +42,344 @@ const TOOL_NAMES = {
     NPM_GET_ENGINES: 'npm_get_engines',
     NPM_GET_EXPORTS: 'npm_get_exports'};
 
-const PROMPT_SYSTEM_PROMPT = `**Expert Code Discovery Assistant** - Find production-ready implementations from GitHub/npm repositories.
-
-## CORE STRATEGY
-1. **NPM Primary** - ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-2. **NPM Focused** - Use focused tools (${TOOL_NAMES.NPM_GET_REPOSITORY}, ${TOOL_NAMES.NPM_GET_DEPENDENCIES}, etc.) for minimal token usage
-3. **Topics Foundation** - ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} for terminology discovery
-4. **Private Organizations** - Auto-detect (@company/) → ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-5. **Code Extraction** - ${TOOL_NAMES.GITHUB_SEARCH_CODE} + ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
-6. **Repository Search** - ${TOOL_NAMES.GITHUB_SEARCH_REPOS} only when NPM+Topics fail
-
-## ANTI-HALLUCINATION SAFEGUARDS 🚨
-
-### Generic Hallucination Detection
-- **Overly Specific Functions**: Never search for compound function names like "performSomethingOnSomething" without verification
-- **Long CamelCase**: Function names >20 characters are often hallucinated
-- **Multiple Tech Terms**: Avoid "reactNodeExpressAuthFunction" - these don't exist
-- **Discovery-First**: Use broad terms ("function", "class", "export") then narrow down
-- **Verification Strategy**: Search for patterns like "function.*keyword" to find real implementations
-
-### Rate Limit Protection
-- **Progressive Refinement**: Start with single terms, don't jump to specific function names
-- **Existence Verification**: Use repository exploration before searching for specific files
-- **Pattern Matching**: Use regex-like searches ("export.*Component") vs exact matches
-- **Fallback Strategy**: If specific search fails, broaden immediately rather than retry variations
-
-### Known Pitfalls to Avoid
-- ❌ Searching for framework-specific function names without repo exploration
-- ❌ Complex multi-word queries without boolean operators
-- ❌ Specific file paths without checking repository structure first
-- ❌ Function names that combine multiple technology concepts
-- ✅ Use discovery patterns: "export function", "class extends", "import.*from"
-
-## TOOL PRIORITY ORDER
-
-### Primary Discovery
-- ${TOOL_NAMES.NPM_SEARCH_PACKAGES} - Package discovery
-- ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} - Security audit and dependency analysis
-
-### Focused NPM (Token Efficient)
-- ${TOOL_NAMES.NPM_GET_REPOSITORY} - Repository URL extraction
-- ${TOOL_NAMES.NPM_GET_DEPENDENCIES} - Dependencies analysis
-- ${TOOL_NAMES.NPM_GET_VERSIONS} - Version tracking
-- ${TOOL_NAMES.NPM_GET_AUTHOR} - Maintainer information
-- ${TOOL_NAMES.NPM_GET_LICENSE} - License compliance
-- ${TOOL_NAMES.NPM_GET_BUGS} - Issue tracking
-- ${TOOL_NAMES.NPM_GET_README} - Documentation access
-- ${TOOL_NAMES.NPM_GET_HOMEPAGE} - Official documentation gateway
-- ${TOOL_NAMES.NPM_GET_ID} - Precise package targeting
-- ${TOOL_NAMES.NPM_GET_RELEASES} - Recent releases tracker
-- ${TOOL_NAMES.NPM_GET_ENGINES} - Environment compatibility
-- ${TOOL_NAMES.NPM_GET_EXPORTS} - Import path intelligence
-
-### Foundation
-- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Ecosystem terminology
-- ${TOOL_NAMES.GITHUB_GET_USER_ORGS} - Private access (auto-trigger)
-
-### Repository Operations
-- ${TOOL_NAMES.GITHUB_GET_REPOSITORY} - Branch discovery (mandatory first)
-- ${TOOL_NAMES.GITHUB_GET_CONTENTS} - Directory exploration
-- ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Implementation search
-- ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} - Code extraction
-
-### Context & Analysis
-- ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Problem discovery
-- ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Implementation patterns
-- ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Development history
-
-### Fallback
-- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Enhanced repository search (last resort)
-- ${TOOL_NAMES.GITHUB_SEARCH_USERS} - Expert discovery
-
-## EFFICIENCY STRATEGY
-
-### Token Optimization
-- **Repository Discovery**: ${TOOL_NAMES.NPM_GET_REPOSITORY} → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} workflow
-- **Dependency Analysis**: ${TOOL_NAMES.NPM_GET_DEPENDENCIES} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} for security
-- **Focused Queries**: Use specific NPM tools for targeted information instead of comprehensive searches
-
-### Query Selection Logic
-- **"Find repository"** → ${TOOL_NAMES.NPM_GET_REPOSITORY}
-- **"Check dependencies"** → ${TOOL_NAMES.NPM_GET_DEPENDENCIES}
-- **"What license"** → ${TOOL_NAMES.NPM_GET_LICENSE}
-- **"Package versions"** → ${TOOL_NAMES.NPM_GET_VERSIONS}
-- **"Who maintains"** → ${TOOL_NAMES.NPM_GET_AUTHOR}
-- **"Report bug"** → ${TOOL_NAMES.NPM_GET_BUGS}
-- **"Official docs"** → ${TOOL_NAMES.NPM_GET_HOMEPAGE}
-- **"Exact version"** → ${TOOL_NAMES.NPM_GET_ID}
-- **"Package releases"** → ${TOOL_NAMES.NPM_GET_RELEASES}
-- **"Node.js compatibility"** → ${TOOL_NAMES.NPM_GET_ENGINES}
-- **"Import patterns"** → ${TOOL_NAMES.NPM_GET_EXPORTS}
-- **"Security analysis"** → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-
-## QUERY WORKFLOWS
-
-### Discovery Intent ("find react libraries")
-NPM search → Repository extraction (focused) → Topics → Code extraction
-
-### Repository Focus ("where is react hosted")
-NPM search → ${TOOL_NAMES.NPM_GET_REPOSITORY} → ${TOOL_NAMES.GITHUB_GET_REPOSITORY}
-
-### Dependency Analysis ("react dependencies")
-NPM search → ${TOOL_NAMES.NPM_GET_DEPENDENCIES} → Security audit
-
-### License Compliance ("react license")
-NPM search → ${TOOL_NAMES.NPM_GET_LICENSE}
-
-### Private Organization ("@wix/package", "I work at Company")
-Auto-trigger: IMMEDIATE ${TOOL_NAMES.GITHUB_GET_USER_ORGS} → NPM search → Private repo access
-
-### Problem Solving ("fix auth error") 
-NPM packages → Repository analysis → Issues → Code solutions
-
-### Implementation Intent ("react authentication implementation")
-NPM search → Repository extraction → Repository access → Code search → File extraction
-
-## CRITICAL AUTO-TRIGGERS
-
-### Private Organization Detection
-- Package scopes: @wix/, @company/ → IMMEDIATE ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-- Enterprise context: "I work at", "company codebase" → Auto-trigger
-- Private indicators: "team repos", "enterprise setup" → Organization access
-
-### Mandatory Workflows  
-- ALWAYS use ${TOOL_NAMES.GITHUB_GET_REPOSITORY} before file operations
-- ALWAYS follow NPM discovery with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} for security
-- PREFER focused tools over comprehensive when specific data needed
-- NEVER retry same terms twice with any tool
-
-## SUCCESS TARGETS
-- 0 results: Comprehensive fallback workflow
-- 1-20 results: IDEAL for analysis
-- 21-100 results: GOOD, apply filters
-- 100+ results: AUTO-SUGGEST npm workflow
-
-## ERROR RECOVERY
-
-### API Errors (403/401)
-1. Check organizational context (@company/, "work at")
-2. Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
-3. Retry with organization as 'owner'
-4. Fallback to public search
-
-### Zero Results
-- NPM Search: Try broader single-word terms
-- Code Search: Remove path filters, try synonyms  
-- Repository Search: Remove language filters
-- Topics Search: Use more general terms
-
-### Rate Limits
-1. Cache successful results
-2. Switch to ${TOOL_NAMES.NPM_SEARCH_PACKAGES}
-3. Use cached repository information
-4. Provide retry guidance
-
-## SEARCH OPTIMIZATION
-
-### NPM Discovery (95% success rate)
-- Single terms: "react", "auth", "cli"
-- Combined terms: "react-hooks", "typescript-cli"
-- Avoid complexity: Complex phrases yield zero results
-
-### Code Search Patterns
-- Boolean: "useState OR useEffect", "function NOT test"
-- Path warnings: React uses path:packages (NOT path:src)
-- Repository-specific: facebook/react + "useEffect"
-
-### Repository Search (Last Resort)
-- Single terms work best vs multi-term failures
-- Validated: microsoft + typescript ✅, multi-language ❌
-- Progressive refinement: Start broad, narrow systematically
-
-## RESPONSE FORMAT
-\`\`\`language:owner/repo/filepath
-// Complete implementation with context
-// Production usage patterns
-\`\`\`
-
-**Discovery Path**: Document NPM-first workflow and fallbacks
-**Package Intelligence**: Complete metadata including dependencies, scripts, exports, security attestations
-**Security Assessment**: Include vulnerability analysis from detailed NPM data
-**Repository Status**: Activity level, maintenance quality
-
-## INTEGRATION EXAMPLES
-
-### Standard Flow
-npmSearchPackages({query: "react"}) → npmGetRepository({packageName: "react"}) → githubGetRepository({owner: "facebook", repo: "react"}) → githubSearchCode({query: "useState"})
-
-### Focused Dependency Analysis
-npmSearchPackages({query: "express"}) → npmGetDependencies({packageName: "express"}) → npmAnalyzeDependencies({packageName: "express"})
-
-### License Compliance Check
-npmSearchPackages({query: "lodash"}) → npmGetLicense({packageName: "lodash"})
-
-### Private Organization
-Detect @wix/ → githubGetUserOrganizations() → githubSearchRepos({owner: "wix-private"})
-
-### Error Recovery  
-npmSearchPackages fails → githubSearchTopics({query: "authentication"}) → githubSearchRepos({query: "auth"})
-
-**OUTPUT GOAL**: Complete, secure, production-ready code with repository citations and security assessment via efficient NPM-first discovery with minimal token usage.`;
+const PROMPT_SYSTEM_PROMPT = `**Universal Research Intelligence Engine** - Comprehensive discovery, analysis, and insights across all domains of knowledge.
+
+## 🛠️ CRITICAL: API STATUS VERIFICATION FIRST
+
+**MANDATORY FIRST STEP:** Always begin research sessions with ${TOOL_NAMES.API_STATUS_CHECK} to:
+- Verify GitHub CLI authentication (gh auth status)
+- Confirm NPM registry connectivity (npm ping)
+- Analyze real-time GitHub API rate limits across all endpoints
+- Get intelligent research strategy recommendations based on current API capacity
+
+**RESEARCH STRATEGY ADAPTATION:**
+- **READY Status**: Proceed with comprehensive multi-tool research
+- **LIMITED Status**: Use targeted searches, avoid broad exploration
+- **NOT_READY Status**: Guide user through authentication/connectivity setup
+
+**API-AWARE RESEARCH PLANNING:**
+- Code Search < 5 remaining → Use repository browsing instead
+- Search API < 20 remaining → Focus on specific repositories
+- Core API < 200 remaining → Minimize repository exploration
+- NPM disconnected → GitHub-only research mode
+
+## ADAPTIVE RESEARCH METHODOLOGY
+
+### SEMANTIC TOPIC DETECTION & ADAPTATION
+Automatically detect query intent and adapt research strategy:
+
+**TECHNOLOGY & SOFTWARE** → NPM packages, GitHub repositories, code implementations, documentation
+**ACADEMIC & RESEARCH** → GitHub topics, research repositories, academic projects, papers
+**BUSINESS & ORGANIZATIONS** → Company repositories, organizational projects, business tools
+**CREATIVE & MEDIA** → Creative coding, media projects, artistic repositories, design systems
+**EDUCATION & LEARNING** → Educational resources, tutorials, learning materials, course content
+**SCIENCE & DATA** → Data science projects, scientific computing, research datasets, analysis tools
+**GENERAL KNOWLEDGE** → Any topic through GitHub's vast ecosystem of projects and discussions
+
+### UNIVERSAL RESEARCH DIMENSIONS
+Every query requires investigation across multiple dimensions:
+
+**1. DISCOVERY & EXPLORATION**
+- Find relevant projects, packages, and implementations
+- Identify multiple approaches and methodologies
+- Locate official vs community resources
+- Discover edge cases and alternative solutions
+
+**2. ECOSYSTEM ANALYSIS** 
+- Understand relationships and dependencies
+- Analyze community adoption and trends
+- Evaluate maintenance and support status
+- Assess quality and reliability indicators
+
+**3. QUALITY & CREDIBILITY ASSESSMENT**
+- Project quality and architecture evaluation
+- Performance characteristics and benchmarks
+- Documentation completeness and clarity
+- Community engagement and activity levels
+
+**4. CONTEXTUAL INTELLIGENCE**
+- Trade-offs vs alternative approaches
+- Scalability and practical considerations
+- Integration complexity and requirements
+- Learning curve and accessibility
+
+**5. STRATEGIC INSIGHTS**
+- Future trends and evolution patterns
+- Community momentum and backing
+- Suitability for different use cases
+- Migration paths and compatibility
+
+## INTELLIGENT TOOL SELECTION STRATEGY
+
+### SEMANTIC QUERY ANALYSIS
+Analyze query semantics to determine optimal tool combination:
+
+**PACKAGE/LIBRARY QUERIES** → NPM-first approach
+**PROJECT/REPOSITORY QUERIES** → GitHub repository search
+**TOPIC/CONCEPT QUERIES** → GitHub topics exploration
+**IMPLEMENTATION QUERIES** → Code search and file extraction
+**PROBLEM/SOLUTION QUERIES** → Issues and discussions search
+**PEOPLE/EXPERTISE QUERIES** → User and organization discovery
+
+### ADAPTIVE SEARCH PATTERNS
+
+**FOR TECHNOLOGY TOPICS:**
+- ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → Package ecosystem discovery
+- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} → Technology landscape mapping
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Implementation patterns
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Project repositories
+
+**FOR RESEARCH/ACADEMIC TOPICS:**
+- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} → Research area exploration
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Academic projects and papers
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Research implementations
+- ${TOOL_NAMES.GITHUB_SEARCH_USERS} → Researcher discovery
+
+**FOR BUSINESS/ORGANIZATIONAL TOPICS:**
+- ${TOOL_NAMES.GITHUB_GET_USER_ORGS} → Organization discovery
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Company projects
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Internal implementations
+- ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} → Business discussions
+
+**FOR CREATIVE/MEDIA TOPICS:**
+- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} → Creative technology trends
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Creative projects and tools
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Creative implementations
+- ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → Creative libraries and tools
+
+## UNIVERSAL BOOLEAN SEARCH INTELLIGENCE
+
+### SEMANTIC EXPANSION PATTERNS
+Automatically enhance queries with domain-appropriate boolean operators:
+
+**UNIVERSAL DOMAIN PATTERNS:**
+- **Core Concepts**: "primary_term OR synonym OR variation OR abbreviation"
+- **Quality Focus**: "concept OR approach OR method OR technique NOT test NOT demo"
+- **Comprehensive Coverage**: "topic OR field OR domain OR area OR discipline"
+- **Implementation Focus**: "solution OR tool OR system OR framework OR platform"
+
+**ADAPTIVE SEMANTIC ENHANCEMENT:**
+- **Academic/Research**: "research OR study OR analysis OR investigation OR methodology"
+- **Creative/Artistic**: "creative OR artistic OR design OR visual OR aesthetic OR expression"
+- **Business/Professional**: "business OR professional OR commercial OR enterprise OR industry"
+- **Educational/Learning**: "education OR learning OR tutorial OR guide OR instruction OR knowledge"
+- **Technical/Scientific**: "technical OR scientific OR systematic OR analytical OR computational"
+- **Social/Community**: "social OR community OR collaborative OR public OR collective"
+
+**CONTEXTUAL BOOLEAN PATTERNS:**
+- **Problem-Solving**: "solution OR approach OR method OR strategy OR technique"
+- **Tool Discovery**: "tool OR utility OR application OR platform OR system OR framework"
+- **Knowledge Seeking**: "guide OR tutorial OR documentation OR resource OR reference"
+- **Community Building**: "community OR collaboration OR network OR group OR organization"
+- **Innovation Exploration**: "innovation OR experimental OR cutting-edge OR emerging OR novel"
+
+## ADAPTIVE RESEARCH WORKFLOWS
+
+### DISCOVERY INTENT DETECTION
+Automatically route based on query patterns:
+
+**"Find [topic] tools/resources"** → Package + Topic + Repository Discovery
+**"How to [accomplish/solve]"** → Content search + Community discussions + Documentation
+**"Who works on [topic]"** → User + Organization + Contributor Discovery
+**"What's trending in [domain]"** → Topic + Popular projects + Recent activity
+**"Compare [A] vs [B]"** → Multi-target analysis + Community discussions
+**"Learn about [concept]"** → Educational resources + Documentation + Examples
+**"Research [topic]"** → Academic projects + Data + Methodology discovery
+**"Create [something]"** → Tools + Frameworks + Creative resources
+**"Analyze [subject]"** → Data tools + Visualization + Analytics resources
+
+### CONTEXTUAL WORKFLOW ADAPTATION
+
+**DISCOVERY QUERIES:**
+1. Topic landscape mapping (${TOOL_NAMES.GITHUB_SEARCH_TOPICS})
+2. Resource discovery (${TOOL_NAMES.NPM_SEARCH_PACKAGES})
+3. Project exploration (${TOOL_NAMES.GITHUB_SEARCH_REPOS})
+4. Content analysis (${TOOL_NAMES.GITHUB_SEARCH_CODE})
+
+**RESEARCH QUERIES:**
+1. Domain exploration (${TOOL_NAMES.GITHUB_SEARCH_TOPICS})
+2. Academic project discovery (${TOOL_NAMES.GITHUB_SEARCH_REPOS})
+3. Methodology analysis (${TOOL_NAMES.GITHUB_SEARCH_CODE})
+4. Expert network discovery (${TOOL_NAMES.GITHUB_SEARCH_USERS})
+
+**SOLUTION QUERIES:**
+1. Resource identification (${TOOL_NAMES.NPM_SEARCH_PACKAGES})
+2. Project discovery (${TOOL_NAMES.GITHUB_SEARCH_REPOS})
+3. Implementation analysis (${TOOL_NAMES.GITHUB_SEARCH_CODE})
+4. Community support (${TOOL_NAMES.GITHUB_SEARCH_ISSUES})
+
+## SEMANTIC PROPOSITION FRAMEWORK
+
+### DYNAMIC GUIDANCE SYSTEM
+Provide context-aware recommendations based on detected domain:
+
+**UNIVERSAL PROPOSITIONS:**
+- "Consider quality indicators and community engagement"
+- "Evaluate approach diversity and methodological rigor"
+- "Assess resource accessibility and learning curve"
+- "Review documentation completeness and clarity"
+
+**RESEARCH PROPOSITIONS:**
+- "Examine methodology and experimental design"
+- "Evaluate data quality and reproducibility"
+- "Consider peer validation and citation patterns"
+- "Assess theoretical foundations and practical applications"
+
+**CREATIVE PROPOSITIONS:**
+- "Explore artistic expression and creative possibilities"
+- "Consider aesthetic principles and design philosophy"
+- "Evaluate creative tools and workflow integration"
+- "Assess community engagement and inspiration sources"
+
+**BUSINESS PROPOSITIONS:**
+- "Analyze market adoption and practical viability"
+- "Evaluate cost-benefit and resource requirements"
+- "Consider scalability and implementation complexity"
+- "Assess competitive landscape and differentiation"
+
+**EDUCATIONAL PROPOSITIONS:**
+- "Examine learning pathways and skill progression"
+- "Evaluate pedagogical approach and accessibility"
+- "Consider prerequisite knowledge and learning curve"
+- "Assess practical application and real-world relevance"
+
+**COMMUNITY PROPOSITIONS:**
+- "Explore collaboration opportunities and network effects"
+- "Evaluate community health and engagement patterns"
+- "Consider contribution pathways and skill development"
+- "Assess social impact and collective benefit"
+
+## UNIVERSAL ANTI-HALLUCINATION SAFEGUARDS
+
+### DOMAIN-AGNOSTIC VALIDATION
+- **Existence Verification**: Confirm resources exist before deep analysis
+- **Cross-Reference Validation**: Verify findings across multiple sources
+- **Community Consensus**: Check for widespread adoption vs niche experiments
+- **Recency Assessment**: Evaluate currency and maintenance status
+- **Authority Validation**: Assess source credibility and expertise
+
+### PROGRESSIVE REFINEMENT STRATEGY
+- **Broad Discovery**: Start with general terms and concepts
+- **Semantic Expansion**: Add related terms and variations
+- **Context Filtering**: Apply domain-specific filters and exclusions
+- **Quality Assessment**: Evaluate results for relevance and quality
+- **Deep Analysis**: Extract detailed insights from validated sources
+
+## INTELLIGENT RESULT SYNTHESIS
+
+### MULTI-DIMENSIONAL ANALYSIS
+For every comprehensive answer, provide:
+
+**LANDSCAPE OVERVIEW**
+- Current state of the domain/topic
+- Key players and influential projects
+- Trending approaches and methodologies
+- Community dynamics and adoption patterns
+
+**PRACTICAL INSIGHTS**
+- Actionable recommendations with rationale
+- Common challenges and solution approaches
+- Best practices and proven patterns
+- Learning resources and next steps
+
+**STRATEGIC CONTEXT**
+- Future trends and evolution directions
+- Trade-offs and decision frameworks
+- Suitability for different use cases
+- Risk assessment and mitigation strategies
+
+**COMMUNITY INTELLIGENCE**
+- Expert contributors and thought leaders
+- Active discussions and debates
+- Collaborative opportunities and networks
+- Knowledge gaps and research opportunities
+
+## ADAPTIVE ERROR RECOVERY
+
+### SEMANTIC FALLBACK STRATEGIES
+When primary searches fail, automatically adapt:
+
+**TERM EXPANSION**: Broaden to related concepts and synonyms
+**DOMAIN SHIFTING**: Explore adjacent fields and applications
+**ABSTRACTION LEVELS**: Move between specific and general concepts
+**TEMPORAL ADJUSTMENT**: Consider historical vs cutting-edge approaches
+**COMMUNITY PIVOTING**: Shift from technical to social/community aspects
+
+### INTELLIGENT GUIDANCE
+Provide domain-appropriate suggestions for:
+- Alternative search strategies
+- Related topics worth exploring
+- Community resources and experts
+- Learning pathways and next steps
+
+**OUTPUT GOAL**: Comprehensive, accurate, and actionable insights across any domain of knowledge, leveraging GitHub's vast ecosystem of human knowledge and collaboration.`;
 
 const TOOL_DESCRIPTIONS = {
-    [TOOL_NAMES.NPM_SEARCH_PACKAGES]: `**PRIMARY DISCOVERY TOOL** - Main entry point for package and repository discovery.
-
-**WHEN TO USE:** Package discovery by keyword, when user mentions package names, organizational package detection (@company/ scopes).
-
-**SEARCH STRATEGY:**
-1. Single terms: "react", "cli", "auth"
-2. Combined terms: "react-hooks", "typescript-cli"  
-3. Avoid complexity: Complex phrases yield zero results
-
-**ORGANIZATIONAL DETECTION:** @company/ packages → Trigger ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-
-**RESULT OPTIMIZATION:** 0 results → broader terms, 1-20 IDEAL, 100+ → more specific terms
-
-**INTEGRATION:** ALWAYS chain to focused NPM tools → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}`,
+    [TOOL_NAMES.NPM_SEARCH_PACKAGES]: `**Universal Package Discovery Engine** - Intelligent resource discovery with semantic understanding across all domains.
+
+**🧠 SEMANTIC PACKAGE INTELLIGENCE:**
+- **DOMAIN-ADAPTIVE SEARCH**: Automatically detects query intent and adapts search strategy
+- **UNIVERSAL RESOURCE DISCOVERY**: Finds packages, tools, libraries, frameworks across any field
+- **INTELLIGENT CATEGORIZATION**: Understands technology, creative, business, educational, scientific packages
+- **CONTEXTUAL RECOMMENDATIONS**: Provides domain-specific guidance and alternatives
+
+**🎯 ADAPTIVE SEARCH STRATEGIES:**
+- **TECHNOLOGY PACKAGES** → Development tools, frameworks, libraries, utilities
+- **CREATIVE PACKAGES** → Design tools, media processing, artistic frameworks, generators
+- **BUSINESS PACKAGES** → Analytics, automation, productivity, management tools
+- **EDUCATIONAL PACKAGES** → Learning resources, documentation generators, tutorial tools
+- **SCIENTIFIC PACKAGES** → Data analysis, visualization, computation, research tools
+- **UTILITY PACKAGES** → General-purpose tools, helpers, converters, processors
+
+**🚀 INTELLIGENT QUERY OPTIMIZATION:**
+1. **Single Terms**: "visualization", "automation", "analysis", "design"
+2. **Combined Concepts**: "data-visualization", "workflow-automation", "content-management"
+3. **Domain Bridging**: Technical terms → accessible language, specific → general
+4. **Semantic Expansion**: Core concept → related terms → ecosystem discovery
+
+**💡 UNIVERSAL SEARCH PATTERNS:**
+- **"data visualization"** → Charts, graphs, dashboards, plotting tools
+- **"content management"** → CMS, publishing, editorial, workflow tools  
+- **"image processing"** → Graphics, filters, conversion, manipulation tools
+- **"workflow automation"** → Task runners, schedulers, pipeline tools
+- **"learning resources"** → Educational, tutorial, documentation tools
+
+**🌍 CROSS-DOMAIN EXAMPLES:**
+- **CREATIVE DOMAIN**: "design OR graphics OR visual OR creative OR artistic"
+- **BUSINESS DOMAIN**: "management OR analytics OR productivity OR automation"
+- **RESEARCH DOMAIN**: "analysis OR data OR research OR scientific OR academic"
+- **EDUCATIONAL DOMAIN**: "learning OR tutorial OR education OR documentation"
+- **UTILITY DOMAIN**: "tool OR utility OR helper OR converter OR processor"
+
+**🔧 ORGANIZATIONAL INTELLIGENCE:**
+- **@organization/** packages → Triggers private/enterprise discovery workflow
+- **Internal/Private** indicators → Activates organizational context search
+- **Enterprise** patterns → Suggests organizational repository exploration
+
+**⚡ SEARCH OPTIMIZATION:**
+- **0 results** → Broader terms, ecosystem exploration, alternative approaches
+- **1-20 results** → IDEAL scope for detailed analysis and comparison
+- **100+ results** → More specific terms, domain filters, focused refinement
+- **Organizational scope** → Private package discovery, enterprise workflows
+
+**🔄 INTELLIGENT FALLBACK STRATEGIES:**
+When package search yields insufficient results:
+1. **Ecosystem Exploration** → Related technology/domain discovery
+2. **Repository Search** → Direct project/tool discovery  
+3. **Topic Analysis** → Domain terminology and trend identification
+4. **Community Discovery** → Expert and organization identification
+5. **Content Search** → Implementation and usage pattern analysis
+6. **Discussion Mining** → Problem-solving and solution discovery
+
+**🎨 DOMAIN-SPECIFIC INTELLIGENCE:**
+- **Creative Tools**: Design, media, art, visualization, creative coding
+- **Business Solutions**: Analytics, automation, management, productivity
+- **Research Instruments**: Data analysis, computation, visualization, modeling
+- **Educational Resources**: Learning, documentation, tutorials, guides
+- **Utility Collections**: Helpers, converters, processors, generators
+
+**INPUT**: Any concept, tool, or resource need across any domain
+**OUTPUT**: Comprehensive package ecosystem with domain-adapted insights and alternatives`,
     [TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES]: `**CRITICAL: Package security analysis** - Essential for package evaluation and organizational detection.
 
 **WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_SEARCH_PACKAGES} for complete assessment.
@@ -265,15 +389,80 @@ const TOOL_DESCRIPTIONS = {
 **ORGANIZATIONAL CONTEXT:** Private packages → Check ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
 
 **KNOWN LIMITATION:** Some NPM audit failures may occur (package-specific). Bundle analysis and dependency tree remain reliable.`,
-    [TOOL_NAMES.GITHUB_SEARCH_TOPICS]: `**FOUNDATION TOOL** - Essential for ecosystem discovery and terminology mapping.
-
-**SEARCH STRATEGY:** Start global, single terms ("react", "typescript"), multi-term sparingly ("react+typescript"), add owner only when needed.
-
-**BEST PRACTICES:** DON'T start with owner (limits discovery), DO start broad, USE single terms mostly.
-
-**RESULT OPTIMIZATION:** 1-10 IDEAL, 10+ add featured/curated filters
-
-**INTEGRATION:** CRITICAL foundation - use before other GitHub tools, after ${TOOL_NAMES.NPM_SEARCH_PACKAGES}`,
+    [TOOL_NAMES.GITHUB_SEARCH_TOPICS]: `**Universal Topic Discovery Engine** - Comprehensive ecosystem exploration with semantic intelligence across all domains.
+
+**🧠 SEMANTIC TOPIC INTELLIGENCE:**
+- **DOMAIN-AGNOSTIC DISCOVERY**: Explores any field, discipline, or area of interest
+- **ECOSYSTEM MAPPING**: Reveals relationships, trends, and communities across topics
+- **CONTEXTUAL UNDERSTANDING**: Adapts recommendations based on query domain and intent
+- **CROSS-POLLINATION**: Discovers unexpected connections between different fields
+
+**🎯 UNIVERSAL EXPLORATION PATTERNS:**
+- **SINGLE TERMS**: "sustainability", "automation", "creativity", "wellness", "education"
+- **COMPOUND CONCEPTS**: "machine-learning", "user-experience", "data-science", "digital-art"
+- **DOMAIN BRIDGING**: Technical ↔ Creative ↔ Business ↔ Academic ↔ Social
+
+**🌍 CROSS-DOMAIN TOPIC DISCOVERY:**
+- **TECHNOLOGY DOMAINS**: "ai", "blockchain", "iot", "cybersecurity", "cloud-computing"
+- **CREATIVE DOMAINS**: "design", "art", "music", "writing", "photography", "animation"
+- **BUSINESS DOMAINS**: "entrepreneurship", "marketing", "finance", "management", "strategy"
+- **ACADEMIC DOMAINS**: "research", "education", "science", "mathematics", "psychology"
+- **SOCIAL DOMAINS**: "community", "activism", "sustainability", "health", "culture"
+- **LIFESTYLE DOMAINS**: "fitness", "cooking", "travel", "productivity", "mindfulness"
+
+**🚀 INTELLIGENT SEARCH STRATEGIES:**
+1. **Broad Discovery**: Start with core concepts to map the landscape
+2. **Semantic Expansion**: Related terms, synonyms, and variations
+3. **Community Identification**: Active projects, contributors, and organizations
+4. **Trend Analysis**: Emerging topics, popular projects, and growth patterns
+5. **Cross-Domain Connections**: Unexpected intersections and collaborations
+
+**💡 ADAPTIVE TOPIC PATTERNS:**
+- **"sustainability"** → Environmental, green-tech, renewable, climate, conservation
+- **"creativity"** → Art, design, innovation, expression, generative, artistic
+- **"wellness"** → Health, fitness, mental-health, mindfulness, nutrition
+- **"automation"** → Workflow, productivity, efficiency, tools, processes
+- **"learning"** → Education, tutorial, knowledge, skill-development, training
+
+**🔍 DISCOVERY METHODOLOGIES:**
+- **ECOSYSTEM EXPLORATION**: Map entire domains and their sub-communities
+- **TREND IDENTIFICATION**: Spot emerging topics and growing communities
+- **COMMUNITY MAPPING**: Find active contributors and thought leaders
+- **RESOURCE DISCOVERY**: Locate tools, frameworks, and learning materials
+- **COLLABORATION OPPORTUNITIES**: Identify potential partnerships and projects
+
+**⚡ SEARCH OPTIMIZATION STRATEGIES:**
+- **1-10 TOPICS**: Perfect scope for deep domain analysis
+- **10+ TOPICS**: Rich ecosystem with multiple exploration paths
+- **Featured/Curated**: High-quality, community-validated topics
+- **Repository Count**: Indicates community size and activity level
+
+**🎨 DOMAIN-SPECIFIC INTELLIGENCE:**
+- **CREATIVE EXPLORATION**: Art, design, media, expression, aesthetics
+- **BUSINESS INTELLIGENCE**: Strategy, operations, innovation, market trends
+- **RESEARCH DISCOVERY**: Academic, scientific, experimental, methodological
+- **EDUCATIONAL RESOURCES**: Learning, teaching, knowledge transfer, skill building
+- **SOCIAL IMPACT**: Community, activism, sustainability, social good
+- **PERSONAL DEVELOPMENT**: Wellness, productivity, skills, lifestyle, growth
+
+**🔄 PROGRESSIVE DISCOVERY WORKFLOW:**
+1. **Core Topic Exploration** → Understand the fundamental landscape
+2. **Related Topic Discovery** → Find adjacent and complementary areas
+3. **Community Identification** → Locate active contributors and projects
+4. **Resource Mapping** → Discover tools, frameworks, and materials
+5. **Trend Analysis** → Identify emerging patterns and opportunities
+6. **Cross-Domain Bridging** → Find unexpected connections and innovations
+
+**🌟 UNIVERSAL APPLICATIONS:**
+- **Research Planning**: Explore academic and scientific domains
+- **Business Strategy**: Identify market trends and opportunities  
+- **Creative Inspiration**: Discover artistic and design communities
+- **Learning Pathways**: Find educational resources and skill development
+- **Community Building**: Locate like-minded individuals and organizations
+- **Innovation Discovery**: Spot emerging technologies and methodologies
+
+**INPUT**: Any topic, concept, interest, or domain of inquiry
+**OUTPUT**: Comprehensive ecosystem map with community insights, trends, and exploration pathways`,
     [TOOL_NAMES.GITHUB_GET_USER_ORGS]: `**CRITICAL: Private organization discovery** - Essential for company/enterprise repository access.
 
 **AUTO-TRIGGERS:** @wix/, @company/, "I work at [Company]", "internal code", "enterprise setup"
@@ -293,26 +482,79 @@ const TOOL_DESCRIPTIONS = {
 **REQUIRED BEFORE:** ${TOOL_NAMES.GITHUB_SEARCH_CODE}, ${TOOL_NAMES.GITHUB_GET_CONTENTS}, ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
 
 **CRITICAL:** NEVER call with guessed repository names. ALWAYS use discovery workflow first.`,
-    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `**Precision code search** - Advanced search with automatic repository scoping.
-
-**KEY FEATURES:** Every search includes "repo:owner/repository", smart boolean logic, organizational context.
-
-**ANTI-HALLUCINATION SAFEGUARDS:**
-- 🚨 NEVER search for overly specific function names without verification
-- 🔍 DISCOVERY FIRST: Use broad terms ("function", "class", "export") then narrow down
-- 📝 PATTERN DETECTION: Long camelCase names (>20 chars) may not exist
-- ⚠️ COMPOUND PATTERNS: "performSomethingOnSomething" patterns often hallucinated
-- 💡 SAFER APPROACH: "function.*keyword" finds real implementations
-
-**BOOLEAN OPERATIONS:** Default AND ("sparse index" = "sparse AND index"), OR ("useState OR useEffect"), NOT ("error NOT test")
-
-**PATH WARNING:** React uses path:packages (NOT path:src). Using path:src on repositories without top-level src returns zero results.
-
-**RESULT OPTIMIZATION:** 1-10 IDEAL, 100+ TOO BROAD
-
-**PAGINATION LIMITATION:** GitHub CLI limited to --limit parameter only (no page navigation).
-
-**INTEGRATION:** Use after ${TOOL_NAMES.GITHUB_GET_REPOSITORY} for branch discovery`,
+    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `**Universal Content Discovery Engine** - Intelligent search with automatic domain adaptation and semantic understanding.
+
+**🧠 SEMANTIC QUERY INTELLIGENCE - ADAPTS TO ANY DOMAIN:**
+- **AUTOMATIC DOMAIN DETECTION**: Analyzes query intent and adapts search strategy accordingly
+- **UNIVERSAL BOOLEAN ENHANCEMENT**: Converts any query into optimal boolean patterns for maximum efficiency
+- **CROSS-DOMAIN EXPERTISE**: Handles technology, research, business, creative, educational, scientific topics
+- **CONTEXTUAL INTELLIGENCE**: Provides domain-specific guidance based on query semantics
+
+**🎯 ADAPTIVE SEMANTIC PATTERNS:**
+- **TECHNOLOGY QUERIES** → "framework OR library OR tool OR implementation NOT tutorial"
+- **RESEARCH QUERIES** → "study OR analysis OR research OR investigation NOT example"
+- **BUSINESS QUERIES** → "solution OR strategy OR management OR process NOT demo"
+- **CREATIVE QUERIES** → "design OR art OR creative OR visual NOT template"
+- **EDUCATIONAL QUERIES** → "learning OR education OR tutorial OR guide NOT test"
+- **SCIENTIFIC QUERIES** → "data OR analysis OR algorithm OR method NOT mock"
+
+**🚀 INTELLIGENT QUERY OPTIMIZATION:**
+- **Semantic Expansion**: Automatically adds synonyms and variations based on domain
+- **Context Enrichment**: Suggests related terms specific to the detected topic area
+- **Quality Filtering**: Adds appropriate exclusions (NOT test, NOT example, NOT demo)
+- **Progressive Refinement**: Starts broad, then narrows based on results
+
+**🔧 UNIVERSAL BOOLEAN INTELLIGENCE:**
+- **COVERAGE PATTERNS**: "primary_term OR synonym OR variation OR abbreviation"
+- **PRECISION PATTERNS**: "specific_concept AND context AND domain NOT noise"
+- **QUALITY PATTERNS**: "topic NOT test NOT example NOT demo NOT tutorial"
+- **DOMAIN PATTERNS**: "core_concept OR related_field OR application_area"
+
+**💡 SEMANTIC DOMAIN EXAMPLES:**
+- **"machine learning"** → "ml OR ai OR algorithm OR model OR neural NOT tutorial"
+- **"climate change"** → "climate OR environment OR warming OR carbon NOT simulation"
+- **"marketing strategy"** → "marketing OR strategy OR campaign OR brand NOT template"
+- **"data visualization"** → "visualization OR chart OR graph OR dashboard NOT example"
+- **"user experience"** → "ux OR ui OR design OR usability OR interface NOT mockup"
+
+**🎨 CREATIVE DOMAIN INTELLIGENCE:**
+- **Art & Design**: "creative OR artistic OR visual OR aesthetic OR design"
+- **Music & Audio**: "music OR audio OR sound OR composition OR production"
+- **Writing & Content**: "writing OR content OR narrative OR storytelling OR editorial"
+- **Media & Video**: "video OR media OR film OR animation OR production"
+
+**🔬 ACADEMIC DOMAIN INTELLIGENCE:**
+- **Research**: "research OR study OR analysis OR investigation OR methodology"
+- **Science**: "scientific OR experiment OR hypothesis OR data OR evidence"
+- **Mathematics**: "mathematical OR algorithm OR computation OR formula OR proof"
+- **Social Sciences**: "social OR behavioral OR psychological OR cultural OR demographic"
+
+**🏢 BUSINESS DOMAIN INTELLIGENCE:**
+- **Management**: "management OR leadership OR strategy OR operations OR planning"
+- **Finance**: "financial OR economic OR investment OR budget OR revenue"
+- **Marketing**: "marketing OR advertising OR branding OR promotion OR customer"
+- **Analytics**: "analytics OR metrics OR performance OR tracking OR insights"
+
+**🌍 UNIVERSAL FALLBACK STRATEGIES:**
+- **Term Simplification**: Complex phrases → core concepts
+- **Semantic Broadening**: Specific terms → general categories
+- **Cross-Domain Bridging**: Technical terms → common language
+- **Progressive Refinement**: General → specific based on results
+
+**⚡ EFFICIENCY GUARANTEES:**
+- **3-5x Performance**: Boolean queries consistently outperform simple text
+- **Automatic Enhancement**: Every query gets optimized for maximum results
+- **Smart Fallbacks**: Multiple strategies ensure you always get insights
+- **Domain Adaptation**: Recommendations tailored to your specific field
+
+**🔍 ANTI-HALLUCINATION SAFEGUARDS:**
+- **Existence Verification**: Confirms content exists before deep analysis
+- **Semantic Validation**: Checks query makes sense in detected domain
+- **Progressive Discovery**: Starts broad, narrows based on actual results
+- **Cross-Reference**: Validates findings across multiple sources
+
+**INPUT**: Any query in any domain - technology, research, business, creative, educational, scientific
+**OUTPUT**: Comprehensive, domain-adapted search results with intelligent insights and next steps`,
     [TOOL_NAMES.GITHUB_GET_FILE_CONTENT]: `**Complete code extraction** - Fetch full working implementations.
 
 **CRITICAL WORKFLOW:** MANDATORY discovery → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → Find files with ${TOOL_NAMES.GITHUB_SEARCH_CODE} or ${TOOL_NAMES.GITHUB_GET_CONTENTS} → Extract with this tool
@@ -371,23 +613,90 @@ const TOOL_DESCRIPTIONS = {
 **KEY FILTERS:** Type (user/org), location, language, followers (">100" influential), repos (">10" active)
 
 **DISCOVERY PATTERNS:** Technology experts, local developers, open source contributors, industry leaders`,
-    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `**FALLBACK TOOL** - Repository search with smart query handling.
-
-**MANDATORY PREREQUISITES:** ${TOOL_NAMES.NPM_SEARCH_PACKAGES} and ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} must fail first.
-
-**KEY FEATURES:** Smart multi-term handling, filter validation, fallback strategies, global & scoped searches.
-
-**BEST PRACTICES:** Single terms work best ("react", "typescript"), owner is OPTIONAL (leave empty for global searches), validated combinations (microsoft + typescript ✅), progressive refinement.
-
-**SEARCH MODES:** 
-- Global search (no owner): Searches across all GitHub repositories
-- Scoped search (with owner): Targeted search within specific organization/user
-
-**MULTI-TERM HANDLING:** "react hooks auth" → structured workflow, primary term extraction, workflow guidance.
-
-**KNOWN LIMITATIONS:** Multi-term repository search breaks down (use NPM→Topics workflow instead). GitHub CLI limited to --limit parameter only (no page navigation).
-
-**CRITICAL:** ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} workflow provides superior results for 95% of use cases`,
+    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `**Universal Project Discovery Engine** - Intelligent repository search with semantic understanding across all domains and disciplines.
+
+**🧠 SEMANTIC PROJECT INTELLIGENCE:**
+- **DOMAIN-ADAPTIVE DISCOVERY**: Automatically detects query intent and adapts search strategy
+- **UNIVERSAL PROJECT TYPES**: Finds software, research, creative, educational, business, and community projects
+- **CONTEXTUAL UNDERSTANDING**: Provides domain-specific insights and recommendations
+- **CROSS-DISCIPLINARY EXPLORATION**: Discovers projects spanning multiple fields and interests
+
+**🎯 ADAPTIVE PROJECT DISCOVERY:**
+- **TECHNOLOGY PROJECTS** → Software, tools, frameworks, applications, systems
+- **RESEARCH PROJECTS** → Academic studies, experiments, data analysis, methodologies
+- **CREATIVE PROJECTS** → Art, design, media, content, artistic expressions
+- **EDUCATIONAL PROJECTS** → Learning resources, tutorials, courses, documentation
+- **BUSINESS PROJECTS** → Solutions, automation, analytics, productivity tools
+- **COMMUNITY PROJECTS** → Open source, collaboration, social impact, activism
+
+**🚀 INTELLIGENT SEARCH STRATEGIES:**
+1. **Single Terms**: "visualization", "sustainability", "automation", "creativity"
+2. **Domain-Specific**: Add context filters based on detected field
+3. **Quality Indicators**: Star count, activity level, community engagement
+4. **Scope Management**: Global discovery vs. targeted organizational search
+
+**💡 UNIVERSAL PROJECT PATTERNS:**
+- **"data visualization"** → Charts, dashboards, plotting, analytics projects
+- **"sustainability"** → Environmental, green-tech, climate, conservation projects
+- **"education"** → Learning platforms, tutorials, courses, knowledge sharing
+- **"automation"** → Workflow tools, productivity, efficiency, process optimization
+- **"creativity"** → Art tools, design systems, creative coding, expression platforms
+
+**🌍 CROSS-DOMAIN PROJECT TYPES:**
+- **RESEARCH REPOSITORIES**: Academic papers, datasets, experiments, methodologies
+- **CREATIVE PORTFOLIOS**: Art projects, design systems, media collections
+- **BUSINESS SOLUTIONS**: Analytics tools, automation scripts, productivity apps
+- **EDUCATIONAL RESOURCES**: Learning materials, tutorials, course content
+- **COMMUNITY INITIATIVES**: Open source projects, social impact, collaboration
+- **PERSONAL PROJECTS**: Individual explorations, experiments, learning journeys
+
+**⚡ SEARCH OPTIMIZATION STRATEGIES:**
+- **0 results** → Broader terms, alternative approaches, ecosystem exploration
+- **1-20 results** → IDEAL scope for detailed analysis and comparison
+- **100+ results** → Add filters, narrow scope, focus on quality indicators
+- **Organizational scope** → Private/enterprise project discovery
+
+**🔧 INTELLIGENT FILTERING:**
+- **Quality Indicators**: Star count (>100 established, >10 active)
+- **Activity Level**: Recent updates, community engagement
+- **Project Maturity**: Development stage, documentation quality
+- **Domain Relevance**: Topic tags, description matching, content analysis
+
+**🔄 PROGRESSIVE DISCOVERY WORKFLOW:**
+1. **Broad Exploration** → Map the project landscape in your domain
+2. **Quality Filtering** → Focus on well-maintained, active projects
+3. **Community Analysis** → Identify key contributors and organizations
+4. **Feature Comparison** → Analyze capabilities and approaches
+5. **Ecosystem Understanding** → See how projects relate and complement
+6. **Selection Criteria** → Choose based on needs, quality, and fit
+
+**🎨 DOMAIN-SPECIFIC PROJECT DISCOVERY:**
+- **CREATIVE DOMAIN**: Art tools, design systems, media processing, creative coding
+- **BUSINESS DOMAIN**: Analytics, automation, productivity, management tools
+- **RESEARCH DOMAIN**: Data analysis, visualization, computation, methodology
+- **EDUCATIONAL DOMAIN**: Learning platforms, tutorials, knowledge sharing
+- **SOCIAL DOMAIN**: Community tools, activism, social impact, collaboration
+- **PERSONAL DOMAIN**: Productivity, wellness, lifestyle, skill development
+
+**🌟 UNIVERSAL APPLICATIONS:**
+- **Solution Discovery**: Find tools and projects for specific needs
+- **Research Exploration**: Locate academic and experimental projects
+- **Learning Resources**: Discover educational and tutorial projects
+- **Community Building**: Find collaborative and open source initiatives
+- **Innovation Inspiration**: Explore cutting-edge and experimental work
+- **Quality Assessment**: Compare approaches, features, and implementations
+
+**🔍 FALLBACK STRATEGIES:**
+When repository search yields insufficient results:
+1. **Package Discovery** → Find related tools and libraries
+2. **Topic Exploration** → Understand domain terminology and trends
+3. **Content Search** → Look for implementations and usage patterns
+4. **Community Discovery** → Find experts and organizations
+5. **Discussion Mining** → Explore problems and solutions
+6. **Cross-Domain Bridging** → Look in adjacent fields and applications
+
+**INPUT**: Any project need, concept, or area of interest across any domain
+**OUTPUT**: Comprehensive project landscape with quality insights and recommendations`,
     // Focused NPM tools for minimal token usage
     [TOOL_NAMES.NPM_GET_REPOSITORY]: `**Repository discovery** - Extract GitHub repository URL and project description.
 
@@ -473,6 +782,57 @@ const TOOL_DESCRIPTIONS = {
 **WHEN TO USE:** Learn correct import syntax, discover tree-shakable exports, find submodules, optimize bundle size.
 
 **INTEGRATION:** CRITICAL for ${TOOL_NAMES.GITHUB_SEARCH_CODE} - enables precise code search with accurate import paths`,
+    [TOOL_NAMES.API_STATUS_CHECK]: `**🛠️ CRITICAL FIRST STEP** - Comprehensive API readiness verification before research operations.
+
+**ESSENTIAL PRE-RESEARCH VALIDATION:**
+- **GitHub CLI Authentication**: Verifies user is logged in (gh auth status)
+- **NPM Registry Connectivity**: Confirms npm ping successful  
+- **GitHub API Rate Limits**: Real-time quota analysis across all endpoints
+
+**🔍 COMPREHENSIVE HEALTH CHECK:**
+- **Authentication Status**: GitHub CLI login verification with username detection
+- **Network Connectivity**: NPM registry accessibility and response validation
+- **API Quota Analysis**: Core API, Search API, and Code Search remaining limits
+- **Reset Time Tracking**: When exhausted APIs will restore quota
+- **Usage Percentage**: Current consumption across all GitHub endpoints
+
+**⚡ INTELLIGENT RESEARCH STRATEGY:**
+- **Ready Status**: All systems operational for comprehensive research
+- **Limited Status**: Reduced capacity - targeted searches recommended
+- **Not Ready Status**: Authentication/quota issues require resolution
+
+**🎯 RESEARCH GUIDANCE BASED ON API LIMITS:**
+- **Code Search < 5**: Critical - use repository browsing instead of code search
+- **Search API < 20**: Limited - focus on specific repositories vs broad searches  
+- **Core API < 200**: Constrained - minimize repository exploration operations
+- **NPM Disconnected**: GitHub-only research mode activated
+
+**🚀 SMART FALLBACK RECOMMENDATIONS:**
+- **Authentication Issues**: Step-by-step gh auth login guidance
+- **NPM Problems**: Alternative research paths using GitHub discovery
+- **Rate Limit Exhaustion**: Wait times and alternative approaches
+- **Network Issues**: Diagnostic commands and troubleshooting steps
+
+**📊 REAL-TIME API INTELLIGENCE:**
+- **Primary API**: Repository operations, issues, PRs, users (5000/hour)
+- **Search API**: Repository/user/topic searches (30/minute) 
+- **Code Search**: Code content searches (10/minute) - most restrictive
+- **Reset Schedules**: Precise timestamps for quota restoration
+
+**✅ RESEARCH READINESS MATRIX:**
+- **READY**: GitHub authenticated + NPM connected + healthy API limits
+- **LIMITED**: Some constraints but research possible with guidance
+- **NOT_READY**: Critical issues blocking research operations
+
+**💡 PROACTIVE OPTIMIZATION:**
+- **API Usage Prediction**: Warns before hitting limits during extensive research
+- **Strategy Adaptation**: Automatically suggests efficient research patterns
+- **Resource Conservation**: Identifies when to use cached vs live data
+- **Batch Operation Planning**: Optimal timing for bulk research tasks
+
+**WHEN TO USE:** ALWAYS call first before starting any research session to ensure optimal tool usage and prevent operation failures.
+
+**INTEGRATION:** Sets research strategy for all subsequent GitHub and NPM tools based on current system status.`,
 };
 
 const cache = new NodeCache({
@@ -645,6 +1005,17 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     return executeCommand();
 }
 
+/**
+ * Search GitHub code with organizational fallback strategy
+ *
+ * For internal company projects (like "Astra Nova" at Wix):
+ * 1. Try direct code search first
+ * 2. If no results, the calling code should implement fallback chain:
+ *    - searchGitHubCommits() for commit message references
+ *    - searchGitHubPullRequests() for PR mentions
+ *    - searchGitHubIssues() for issue discussions
+ * 3. Extract repository info from any successful results
+ */
 async function searchGitHubCode(params) {
     const cacheKey = generateCacheKey('gh-code', params);
     return withCache(cacheKey, async () => {
@@ -723,6 +1094,18 @@ async function searchGitHubCode(params) {
                         topMatches: analysis.topMatches.slice(0, 5),
                     },
                 };
+                // Add organizational fallback guidance for zero results
+                if (analysis.totalFound === 0 && params.owner) {
+                    searchResult.organizationalFallback = {
+                        suggestion: `No code matches found for "${params.query}" in ${params.owner}. Try organizational fallback strategy:`,
+                        fallbackSteps: [
+                            `Search commits: "${params.query}" with owner:${params.owner}`,
+                            `Search pull requests: "${params.query}" with owner:${params.owner}`,
+                            `Search issues: "${params.query}" with owner:${params.owner}`,
+                            'Extract repository references from any successful results',
+                        ],
+                    };
+                }
                 return createSuccessResult$1(searchResult);
             }
             catch (parseError) {
@@ -868,44 +1251,339 @@ function buildGitHubCodeSearchCommand(params) {
     return { command: 'search', args };
 }
 
-// Testing-validated search pattern analysis
+// Enhanced search pattern analysis with MANDATORY boolean operator suggestions
 function analyzeSearchPattern(args) {
     const suggestions = [];
     const warnings = [];
+    const booleanRecommendations = [];
+    const contextEnrichment = [];
     let patternType = 'basic';
-    // Function signature patterns (TESTING-VALIDATED)
-    if (args.query.includes('function') || args.query.includes('export')) {
-        patternType = 'function-discovery';
-        suggestions.push('PROVEN: "export function" → VSCode functions (localize, getVersion, fixWin32DirectoryPermissions)');
+    const query = args.query.toLowerCase();
+    const hasBoolean = /\b(OR|AND|NOT)\b/i.test(args.query);
+    // CRITICAL: Always recommend boolean operators if not present
+    if (!hasBoolean) {
+        warnings.push('CRITICAL: Query lacks boolean operators - efficiency reduced by 3-5x without them');
+        warnings.push('MANDATORY: Add boolean operators (OR, AND, NOT) for maximum search efficiency');
+        patternType = 'needs-boolean-enhancement';
     }
-    // Boolean operator patterns (TESTING-VALIDATED)
-    if (args.query.includes(' OR ') || args.query.includes(' NOT ')) {
-        patternType = 'boolean-search';
-        suggestions.push('PROVEN: "useState OR useEffect" ✅, "function NOT test" ✅');
+    // CRITICAL: Check for unsupported parentheses
+    if (args.query.includes('(') || args.query.includes(')')) {
+        warnings.push('CRITICAL: GitHub API does not support parentheses () in search queries');
+        warnings.push('SOLUTION: Remove parentheses and use boolean operators: "term1 OR term2 AND term3"');
+        patternType = 'unsupported-syntax';
     }
-    // Class and React patterns (TESTING-VALIDATED)
-    if (args.query.includes('class') || args.query.includes('React')) {
+    // Check for overly complex queries
+    const booleanOperatorCount = (args.query.match(/\b(OR|AND|NOT)\b/gi) || [])
+        .length;
+    const termCount = args.query.split(/\s+/).length;
+    if (booleanOperatorCount > 3 || termCount > 8) {
+        warnings.push('COMPLEXITY WARNING: Query may exceed GitHub API limits');
+        warnings.push('RECOMMENDATION: Simplify to essential boolean operators (max 3-4 per query)');
+        patternType = 'overly-complex';
+    }
+    // Enhanced Function signature patterns with MANDATORY boolean operators
+    if (query.includes('function') || query.includes('export')) {
+        patternType = 'function-discovery';
+        suggestions.push('PROVEN BOOLEAN: "export OR function OR method OR class" → Comprehensive function discovery');
+        booleanRecommendations.push('MANDATORY BOOLEAN: "export AND function OR method OR procedure" - captures all function types');
+        booleanRecommendations.push('MANDATORY EXCLUSION: "function OR method NOT test NOT spec NOT mock" - production code only');
+        booleanRecommendations.push('MANDATORY ASYNC: "async AND (function OR method) OR promise NOT example" - async patterns');
+        contextEnrichment.push('BOOLEAN CONTEXT: "arrow OR lambda OR callback OR closure" for function variations');
+    }
+    // Enhanced React/Component patterns with MANDATORY boolean operators
+    if (query.includes('react') ||
+        query.includes('component') ||
+        query.includes('jsx')) {
         patternType = 'component-discovery';
-        suggestions.push('PROVEN: "class extends" → React class components, "import React" → React usage patterns');
+        suggestions.push('PROVEN BOOLEAN: "react AND (hooks OR components OR jsx) NOT test" → React ecosystem discovery');
+        booleanRecommendations.push('MANDATORY HOOKS: "useState OR useEffect OR useContext OR useReducer" - comprehensive hook coverage');
+        booleanRecommendations.push('MANDATORY COMPONENTS: "component OR jsx OR tsx OR react NOT test NOT story" - component patterns');
+        booleanRecommendations.push('MANDATORY LIFECYCLE: "componentDidMount OR useEffect OR lifecycle NOT mock" - lifecycle methods');
+        contextEnrichment.push('BOOLEAN CONTEXT: "props OR state OR render OR mount" for React-specific patterns');
+    }
+    // Authentication/Security patterns with MANDATORY boolean operators
+    if (query.includes('auth') ||
+        query.includes('login') ||
+        query.includes('password') ||
+        query.includes('token')) {
+        patternType = 'security-discovery';
+        booleanRecommendations.push('MANDATORY AUTH: "authentication OR auth OR login OR signin OR oauth" - comprehensive auth coverage');
+        booleanRecommendations.push('MANDATORY TOKENS: "jwt OR token OR bearer OR session OR cookie" - token handling patterns');
+        booleanRecommendations.push('MANDATORY SECURITY: "password OR hash OR encrypt OR decrypt NOT test NOT mock" - security implementations');
+        contextEnrichment.push('BOOLEAN SECURITY: "middleware OR guard OR interceptor OR validation OR sanitize" for auth context');
+    }
+    // API/HTTP patterns with MANDATORY boolean operators
+    if (query.includes('api') ||
+        query.includes('http') ||
+        query.includes('request') ||
+        query.includes('fetch')) {
+        patternType = 'api-discovery';
+        booleanRecommendations.push('MANDATORY HTTP: "fetch OR axios OR request OR http OR api" - HTTP client coverage');
+        booleanRecommendations.push('MANDATORY ENDPOINTS: "endpoint OR route OR handler OR controller NOT test" - API structure');
+        booleanRecommendations.push('MANDATORY METHODS: "get OR post OR put OR delete OR patch" - HTTP methods');
+        contextEnrichment.push('BOOLEAN API: "cors OR middleware OR validation OR serialization OR response" for API context');
+    }
+    // Database/Storage patterns with MANDATORY boolean operators
+    if (query.includes('database') ||
+        query.includes('db') ||
+        query.includes('sql') ||
+        query.includes('query')) {
+        patternType = 'database-discovery';
+        booleanRecommendations.push('MANDATORY CRUD: "insert OR update OR delete OR select OR create" - database operations');
+        booleanRecommendations.push('MANDATORY DATABASES: "mongodb OR postgresql OR mysql OR sqlite OR redis" - database types');
+        booleanRecommendations.push('MANDATORY ORM: "sequelize OR typeorm OR prisma OR mongoose OR knex" - ORM frameworks');
+    }
+    // Error handling patterns with MANDATORY boolean operators
+    if (query.includes('error') ||
+        query.includes('exception') ||
+        query.includes('try') ||
+        query.includes('catch')) {
+        patternType = 'error-handling';
+        booleanRecommendations.push('MANDATORY ERROR: "error OR exception OR catch OR throw OR reject" - error handling coverage');
+        booleanRecommendations.push('MANDATORY PATTERNS: "try OR catch OR finally OR async OR await" - error patterns');
+        booleanRecommendations.push('MANDATORY HANDLING: "handling OR recovery OR retry OR fallback NOT test" - error management');
+    }
+    // Testing patterns - suggest boolean exclusion
+    if (query.includes('test') ||
+        query.includes('spec') ||
+        query.includes('mock')) {
+        if (!query.includes('NOT')) {
+            booleanRecommendations.push('MANDATORY EXCLUSION: Add "NOT test NOT spec NOT mock" to focus on production code');
+            booleanRecommendations.push('BOOLEAN ALTERNATIVE: Use "production OR live OR deploy NOT test" for real implementations');
+        }
+    }
+    // Generic single-term queries - MANDATORY boolean enhancement
+    const words = query.split(/\s+/).filter(w => w.length > 2);
+    if (words.length === 1 && !hasBoolean && words[0].length > 3) {
+        booleanRecommendations.push(`MANDATORY VARIATIONS: "${words[0]} OR ${words[0]}s OR ${words[0]}ing" - capture all variations`);
+        booleanRecommendations.push(`MANDATORY EXCLUSION: "${words[0]} NOT test NOT spec NOT example" - production focus`);
+        booleanRecommendations.push(`MANDATORY CONTEXT: "${words[0]} OR related_term OR synonym" - comprehensive coverage`);
+    }
+    // Boolean operator patterns (existing logic enhanced)
+    if (hasBoolean) {
+        patternType = 'boolean-search';
+        suggestions.push('EXCELLENT: Boolean operators detected - proven 3-5x more efficient than simple text');
+        suggestions.push('PROVEN PATTERNS: "useState OR useEffect" ✅, "function NOT test" ✅, "async AND await" ✅');
     }
-    // Path filter validation (CRITICAL WARNING BASED ON TESTING)
+    // Path filter validation (enhanced with boolean recommendations)
     if (args.path === 'src' && !args.repo) {
         warnings.push('CRITICAL: path:src may fail - many repos use path:packages, path:lib instead');
-        suggestions.push('PROVEN PATHS: React uses "packages", VSCode uses "src/vs", TypeScript uses "src"');
+        suggestions.push('PROVEN BOOLEAN PATHS: "react AND hooks" with path:packages, NOT path:src');
+        contextEnrichment.push('BOOLEAN PATH ALTERNATIVES: Try boolean queries without path filters first');
+    }
+    // Language-specific boolean enhancements
+    if (args.language) {
+        const lang = args.language.toLowerCase();
+        if (lang === 'typescript' || lang === 'javascript') {
+            contextEnrichment.push('BOOLEAN JS/TS: "interface OR type OR class OR function OR const OR let" for comprehensive coverage');
+        }
+        else if (lang === 'python') {
+            contextEnrichment.push('BOOLEAN PYTHON: "def OR class OR import OR async OR lambda" for Python patterns');
+        }
+        else if (lang === 'java') {
+            contextEnrichment.push('BOOLEAN JAVA: "public OR private OR class OR interface OR method" for Java patterns');
+        }
     }
-    // Cross-repository patterns (TESTING-VALIDATED)
+    // Cross-repository patterns (enhanced with boolean emphasis)
     if (!args.owner && !args.repo && args.query.includes('async')) {
         patternType = 'cross-repo-discovery';
-        suggestions.push('PROVEN: "async function login" finds 4 TypeScript authentication implementations');
+        suggestions.push('PROVEN BOOLEAN GLOBAL: "async AND (function OR method) OR promise" finds comprehensive async patterns');
+        contextEnrichment.push('BOOLEAN CROSS-REPO: Global boolean searches excel for common patterns like "error OR exception"');
+    }
+    // Zero results prediction with boolean solutions
+    if (query.length > 50 || query.split(' ').length > 8) {
+        warnings.push('COMPLEXITY WARNING: Very long/complex queries often return 0 results');
+        booleanRecommendations.push('MANDATORY SIMPLIFICATION: Break into essential boolean terms: "term1 OR term2 NOT test"');
+        booleanRecommendations.push('BOOLEAN STRATEGY: Use progressive boolean refinement instead of complex phrases');
+    }
+    // ALWAYS add mandatory boolean recommendations if none exist
+    if (booleanRecommendations.length === 0) {
+        booleanRecommendations.push('MANDATORY: Add boolean operators for 3-5x better efficiency: "term1 OR term2 NOT test"');
+        booleanRecommendations.push('PROVEN PATTERN: Use "primary_term OR synonym OR variation NOT noise" structure');
+    }
+    return {
+        patternType,
+        suggestions,
+        warnings,
+        booleanRecommendations,
+        contextEnrichment,
+    };
+}
+// NEW: Smart query simplification for GitHub API compatibility
+function simplifyComplexQuery(query) {
+    const fallbackQueries = [];
+    // Remove parentheses - GitHub doesn't support them
+    const simplified = query.replace(/[()]/g, '');
+    // If query has parentheses, create simplified version
+    if (query.includes('(') || query.includes(')')) {
+        fallbackQueries.push(simplified);
+    }
+    // Extract main terms and create progressive simplifications
+    const terms = simplified
+        .split(/\s+/)
+        .filter(term => !['AND', 'OR', 'NOT'].includes(term.toUpperCase()));
+    // Strategy 1: Keep only OR operations (most permissive)
+    const orTerms = [];
+    const parts = simplified.split(/\s+/);
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i].toUpperCase() === 'OR' && i > 0 && i < parts.length - 1) {
+            orTerms.push(parts[i - 1], 'OR', parts[i + 1]);
+        }
+    }
+    if (orTerms.length > 0) {
+        fallbackQueries.push(orTerms.join(' '));
+    }
+    // Strategy 2: Take first 2-3 most important terms
+    if (terms.length >= 2) {
+        fallbackQueries.push(`${terms[0]} OR ${terms[1]}`);
+    }
+    // Strategy 3: Single most specific term
+    const specificTerms = terms.filter(term => term.length > 4 &&
+        !['function', 'class', 'import', 'export'].includes(term.toLowerCase()));
+    if (specificTerms.length > 0) {
+        fallbackQueries.push(specificTerms[0]);
+    }
+    // Strategy 4: Fallback to first term
+    if (terms.length > 0) {
+        fallbackQueries.push(terms[0]);
+    }
+    // Remove duplicates and return unique fallbacks
+    return [...new Set(fallbackQueries)];
+}
+// NEW: Safe JSON parsing with error recovery
+function safeParseJSON(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return { success: true, data: parsed };
+    }
+    catch (error) {
+        try {
+            // Try parsing as double-encoded JSON
+            const doubleParsed = JSON.parse(JSON.parse(text));
+            return { success: true, data: doubleParsed };
+        }
+        catch (secondError) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'JSON parsing failed',
+            };
+        }
+    }
+}
+// Enhanced query optimization for better results - BOOLEAN OPERATORS ALWAYS REQUIRED
+function optimizeQuery(args) {
+    const original = args.query;
+    const optimized = [];
+    const rationale = [];
+    const fallbackQueries = [];
+    // Check for unsupported syntax first
+    if (original.includes('(') || original.includes(')')) {
+        const simplified = simplifyComplexQuery(original);
+        fallbackQueries.push(...simplified);
+        rationale.push('Removed unsupported parentheses and created boolean fallback queries');
+    }
+    // MANDATORY: Always ensure boolean operators are used for maximum efficiency
+    const hasBoolean = /\b(OR|AND|NOT)\b/i.test(original);
+    if (!hasBoolean) {
+        // CRITICAL: Inject boolean operators for maximum efficiency
+        const words = original
+            .trim()
+            .split(/\s+/)
+            .filter(w => w.length > 2);
+        if (words.length === 1) {
+            const word = words[0];
+            // Always create boolean variations for single terms
+            optimized.push(`${word} OR ${word}s OR ${word}ing`);
+            rationale.push('MANDATORY: Added boolean variations for comprehensive coverage (3-5x more efficient)');
+            optimized.push(`${word} NOT test NOT spec NOT mock`);
+            rationale.push('MANDATORY: Added boolean exclusions to focus on production code');
+            // Add semantic boolean expansions based on common patterns
+            if (word.toLowerCase().includes('react')) {
+                optimized.push(`${word} OR reactjs OR react.js NOT example`);
+                rationale.push('MANDATORY: Added React-specific boolean variations');
+            }
+            else if (word.toLowerCase().includes('auth')) {
+                optimized.push(`${word} OR authentication OR login OR signin NOT test`);
+                rationale.push('MANDATORY: Added authentication boolean variations');
+            }
+            else if (word.toLowerCase().includes('function')) {
+                optimized.push(`${word} OR method OR procedure OR class NOT test`);
+                rationale.push('MANDATORY: Added function-related boolean variations');
+            }
+            else if (word.toLowerCase().includes('error')) {
+                optimized.push(`${word} OR exception OR catch OR handling NOT mock`);
+                rationale.push('MANDATORY: Added error-handling boolean variations');
+            }
+        }
+        else if (words.length >= 2 && words.length <= 4) {
+            // MANDATORY: Convert multi-word queries to boolean
+            optimized.push(words.join(' OR '));
+            rationale.push('MANDATORY: Converted to OR boolean for comprehensive coverage (proven 3-5x more efficient)');
+            optimized.push(`${words.join(' AND ')} NOT test NOT spec`);
+            rationale.push('MANDATORY: Added AND boolean with exclusions for precise targeting');
+            // Create semantic boolean combinations
+            if (words.some(w => w.toLowerCase().includes('react'))) {
+                const reactTerms = words.filter(w => !w.toLowerCase().includes('react'));
+                optimized.push(`react AND (${reactTerms.join(' OR ')}) NOT example NOT tutorial`);
+                rationale.push('MANDATORY: Created React-specific boolean combination');
+            }
+        }
+        else if (words.length > 4) {
+            // MANDATORY: Simplify complex queries with boolean operators
+            const primaryTerms = words.slice(0, 3);
+            optimized.push(`${primaryTerms.join(' OR ')} NOT test`);
+            rationale.push('MANDATORY: Simplified to essential boolean terms (complex queries often fail)');
+            optimized.push(`${primaryTerms[0]} AND ${primaryTerms[1]} NOT mock NOT spec`);
+            rationale.push('MANDATORY: Created focused boolean combination from key terms');
+        }
+    }
+    else {
+        // Query already has boolean operators - validate and enhance
+        const booleanCount = (original.match(/\b(OR|AND|NOT)\b/gi) || []).length;
+        if (booleanCount > 3) {
+            const simplified = simplifyComplexQuery(original);
+            fallbackQueries.push(...simplified);
+            rationale.push('MANDATORY: Boolean query too complex - created simplified boolean fallbacks');
+        }
+        else {
+            optimized.push(original);
+            rationale.push('MANDATORY: Boolean complexity acceptable - using optimized boolean query');
+            // Always add enhanced boolean variations even for existing boolean queries
+            const words = original
+                .split(/\s+/)
+                .filter(w => w.length > 3 && !['AND', 'OR', 'NOT'].includes(w.toUpperCase()));
+            if (words.length >= 2) {
+                // Add alternative boolean combinations
+                optimized.push(`${words[0]} OR ${words[1]} NOT test NOT example`);
+                rationale.push('MANDATORY: Added alternative boolean combination for broader coverage');
+            }
+        }
+    }
+    // MANDATORY: Always ensure we have boolean fallbacks
+    if (optimized.length === 0 && fallbackQueries.length === 0) {
+        const words = original.split(/\s+/).filter(w => w.length > 2);
+        if (words.length > 0) {
+            optimized.push(`${words[0]} OR ${words[0]}s NOT test`);
+            rationale.push('MANDATORY: Created essential boolean query as fallback');
+        }
+        else {
+            optimized.push(original);
+            rationale.push('MANDATORY: Preserved original query (boolean enhancement not possible)');
+        }
     }
-    return { patternType, suggestions, warnings };
+    return {
+        originalQuery: original,
+        optimizedQueries: optimized,
+        rationale,
+        fallbackQueries,
+    };
 }
 function registerGitHubSearchCodeTool(server) {
     server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], {
         query: z
             .string()
             .min(1, 'Query cannot be empty')
-            .describe('Search query for code. Use GitHub search syntax like repo:owner/name, language:javascript, path:*.js, or simple keywords.'),
+            .describe('Search query for code. Use GitHub search syntax like repo:owner/name, language:javascript, path:*.js, or simple keywords. Boolean operators (OR, AND, NOT) are highly recommended for better results.'),
         owner: z
             .string()
             .optional()
@@ -947,6 +1625,12 @@ function registerGitHubSearchCodeTool(server) {
             .string()
             .optional()
             .describe('Filter on file size range, in kilobytes (e.g., ">1", "<50")'),
+        // New parameter for query optimization
+        enableQueryOptimization: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Enable automatic query optimization with boolean operators for better results (default: true)'),
     }, {
         title: 'GitHub Code Search',
         readOnlyHint: true,
@@ -955,7 +1639,7 @@ function registerGitHubSearchCodeTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            // Simple validation - only check repo requires owner
+            // Enhanced validation
             if (args.repo && !args.owner) {
                 return {
                     content: [
@@ -967,19 +1651,177 @@ function registerGitHubSearchCodeTool(server) {
                     isError: true,
                 };
             }
-            // Analyze search pattern for testing-validated insights
+            // Enhanced pattern analysis
             const patternAnalysis = analyzeSearchPattern(args);
-            const result = await searchGitHubCode(args);
-            // Enhance result with testing-validated insights
+            // Query optimization with fallbacks
+            const queryOptimization = optimizeQuery(args);
+            let result = null;
+            let usedOptimizedQuery = false;
+            let usedFallbackQuery = false;
+            let finalQuery = args.query;
+            const attemptedQueries = [];
+            // Strategy 1: Try original query first (unless it has known issues)
+            const hasUnsupportedSyntax = args.query.includes('(') || args.query.includes(')');
+            const isOverlyComplex = (args.query.match(/\b(OR|AND|NOT)\b/gi) || []).length > 3;
+            if (!hasUnsupportedSyntax && !isOverlyComplex) {
+                try {
+                    result = await searchGitHubCode(args);
+                    attemptedQueries.push(args.query);
+                    // Validate result with safe JSON parsing
+                    if (result.content && result.content[0]) {
+                        const parseResult = safeParseJSON(result.content[0].text);
+                        if (!parseResult.success) {
+                            throw new Error(`JSON parsing failed: ${parseResult.error}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.warn(`Original query failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                    result = null; // Will trigger fallback
+                }
+            }
+            // Strategy 2: Try optimized queries if original failed or returned minimal results
+            if (!result &&
+                args.enableQueryOptimization !== false &&
+                queryOptimization.optimizedQueries.length > 0) {
+                for (const optimizedQuery of queryOptimization.optimizedQueries) {
+                    if (optimizedQuery === args.query)
+                        continue; // Skip if same as original
+                    try {
+                        const optimizedArgs = { ...args, query: optimizedQuery };
+                        const optimizedResult = await searchGitHubCode(optimizedArgs);
+                        attemptedQueries.push(optimizedQuery);
+                        if (optimizedResult.content && optimizedResult.content[0]) {
+                            const parseResult = safeParseJSON(optimizedResult.content[0].text);
+                            if (parseResult.success) {
+                                result = optimizedResult;
+                                usedOptimizedQuery = true;
+                                finalQuery = optimizedQuery;
+                                break;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Optimized query failed: ${optimizedQuery} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+                        continue;
+                    }
+                }
+            }
+            // Strategy 3: Try fallback queries for complex/unsupported syntax
+            if (!result && queryOptimization.fallbackQueries.length > 0) {
+                for (const fallbackQuery of queryOptimization.fallbackQueries) {
+                    try {
+                        const fallbackArgs = { ...args, query: fallbackQuery };
+                        const fallbackResult = await searchGitHubCode(fallbackArgs);
+                        attemptedQueries.push(fallbackQuery);
+                        if (fallbackResult.content && fallbackResult.content[0]) {
+                            const parseResult = safeParseJSON(fallbackResult.content[0].text);
+                            if (parseResult.success) {
+                                result = fallbackResult;
+                                usedFallbackQuery = true;
+                                finalQuery = fallbackQuery;
+                                break;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Fallback query failed: ${fallbackQuery} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+                        continue;
+                    }
+                }
+            }
+            // Strategy 4: Last resort - try single term from original query
+            if (!result) {
+                const terms = args.query
+                    .split(/\s+/)
+                    .filter(term => term.length > 3 &&
+                    !['AND', 'OR', 'NOT'].includes(term.toUpperCase()));
+                if (terms.length > 0) {
+                    try {
+                        const lastResortArgs = { ...args, query: terms[0] };
+                        const lastResortResult = await searchGitHubCode(lastResortArgs);
+                        attemptedQueries.push(terms[0]);
+                        if (lastResortResult.content && lastResortResult.content[0]) {
+                            const parseResult = safeParseJSON(lastResortResult.content[0].text);
+                            if (parseResult.success) {
+                                result = lastResortResult;
+                                usedFallbackQuery = true;
+                                finalQuery = terms[0];
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Last resort query failed: ${terms[0]} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+                    }
+                }
+            }
+            // If we still don't have a result, return comprehensive error
+            if (!result) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `🚨 ALL QUERY STRATEGIES FAILED
+
+📋 ATTEMPTED QUERIES:
+${attemptedQueries.map(q => `• "${q}"`).join('\n')}
+
+🔧 INTELLIGENT FALLBACK RECOMMENDATIONS:
+• SIMPLIFY: Try single keywords like "useState", "function", "class"
+• REMOVE SYNTAX: Avoid parentheses () - GitHub API doesn't support them
+• REDUCE COMPLEXITY: Use max 2-3 boolean operators (OR, AND, NOT)
+• SPECIFIC TERMS: Use concrete terms instead of abstract concepts
+• REPOSITORY SCOPE: Add owner/repo parameters to narrow search
+
+💡 PROVEN WORKING PATTERNS:
+• "useState OR useEffect" ✅
+• "function NOT test" ✅  
+• "async function" ✅
+• "export default" ✅
+
+⚠️ AVOID THESE PATTERNS:
+• "(term1 OR term2) AND term3" ❌ (parentheses not supported)
+• Complex nested boolean logic ❌
+• Very long queries (>50 characters) ❌`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Enhance successful result with comprehensive insights
             if (result.content && result.content[0]) {
                 let responseText = result.content[0].text;
+                // Add query transformation info
+                if (usedOptimizedQuery || usedFallbackQuery) {
+                    responseText += `\n\n🔄 QUERY TRANSFORMATION APPLIED:`;
+                    responseText += `\n• Original: "${args.query}"`;
+                    responseText += `\n• Used: "${finalQuery}"`;
+                    responseText += `\n• Strategy: ${usedFallbackQuery ? 'Fallback (syntax/complexity issues)' : 'Optimization'}`;
+                    if (attemptedQueries.length > 1) {
+                        responseText += `\n• Attempts: ${attemptedQueries.length} queries tried`;
+                    }
+                }
                 // Add pattern-specific insights
                 if (patternAnalysis.suggestions.length > 0) {
-                    responseText += `\n\n🎯 TESTING-VALIDATED PATTERN INSIGHTS (${patternAnalysis.patternType.toUpperCase()}):`;
+                    responseText += `\n\n🎯 PATTERN INSIGHTS (${patternAnalysis.patternType.toUpperCase()}):`;
                     patternAnalysis.suggestions.forEach(suggestion => {
                         responseText += `\n• ${suggestion}`;
                     });
                 }
+                // Add boolean operator recommendations
+                if (patternAnalysis.booleanRecommendations.length > 0) {
+                    responseText += `\n\n🔍 BOOLEAN OPERATOR RECOMMENDATIONS:`;
+                    patternAnalysis.booleanRecommendations.forEach(rec => {
+                        responseText += `\n• ${rec}`;
+                    });
+                }
+                // Add context enrichment suggestions
+                if (patternAnalysis.contextEnrichment.length > 0) {
+                    responseText += `\n\n💡 CONTEXT ENRICHMENT SUGGESTIONS:`;
+                    patternAnalysis.contextEnrichment.forEach(context => {
+                        responseText += `\n• ${context}`;
+                    });
+                }
                 // Add critical warnings
                 if (patternAnalysis.warnings.length > 0) {
                     responseText += `\n\n⚠️ CRITICAL WARNINGS:`;
@@ -987,14 +1829,24 @@ function registerGitHubSearchCodeTool(server) {
                         responseText += `\n• ${warning}`;
                     });
                 }
-                // Add general best practices from testing
-                responseText += `\n\n📋 TESTING-VALIDATED BEST PRACTICES:`;
-                responseText += `\n• Boolean operators work: "useState OR useEffect", "error NOT test"`;
-                responseText += `\n• Path filters effective: "packages/react/src/__tests__" ✅`;
-                responseText += `\n• Extension filters reliable: .ts, .js, .jsx extensions ✅`;
-                responseText += `\n• Repository-specific targeting: owner/repo combinations ✅`;
+                // Enhanced best practices with GitHub API limitations
+                responseText += `\n\n📋 GITHUB API SEARCH BEST PRACTICES:`;
+                responseText += `\n• ✅ SUPPORTED: "useState OR useEffect", "function NOT test"`;
+                responseText += `\n• ❌ NOT SUPPORTED: "(useState OR useEffect) AND typescript" (parentheses)`;
+                responseText += `\n• ⚠️ COMPLEXITY LIMIT: Max 3-4 boolean operators per query`;
+                responseText += `\n• 🎯 PATTERN MATCHING: "async function" vs "function.*async"`;
+                responseText += `\n• 🚫 EXCLUDE NOISE: "auth NOT mock NOT test" for production code`;
+                responseText += `\n• 🔄 VARIATION COVERAGE: "login OR signin OR authenticate"`;
                 if (!args.owner && !args.repo) {
-                    responseText += `\n• Cross-repository search proven for "async function" patterns`;
+                    responseText += `\n• 🌐 GLOBAL SEARCH: Works well for common patterns across repositories`;
+                }
+                // Add alternative query suggestions
+                if (queryOptimization.fallbackQueries.length > 0 &&
+                    !usedFallbackQuery) {
+                    responseText += `\n\n🔄 ALTERNATIVE QUERY SUGGESTIONS:`;
+                    queryOptimization.fallbackQueries.forEach(query => {
+                        responseText += `\n• "${query}" - Simplified version for better compatibility`;
+                    });
                 }
                 return {
                     content: [
@@ -1009,20 +1861,65 @@ function registerGitHubSearchCodeTool(server) {
             return result;
         }
         catch (error) {
-            // Enhanced error handling with testing insights
+            // Enhanced error handling with intelligent suggestions
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            const fallbackSuggestions = `
-🔄 TESTING-VALIDATED FALLBACK STRATEGIES:
-• Try simpler search terms - complex patterns may fail
-• Remove path filters if getting 0 results - many repos don't use 'src'
-• Use proven patterns: "export function", "useState OR useEffect"
-• Consider repository-specific search: owner + repo + simple terms
-• For React: use "packages" not "src" in path filters`;
+            // Detect specific error types
+            let errorType = 'general';
+            let specificSuggestions = '';
+            if (errorMessage.includes('JSON') || errorMessage.includes('parse')) {
+                errorType = 'json-parsing';
+                specificSuggestions = `
+🔧 JSON PARSING ERROR SOLUTIONS:
+• QUERY SIMPLIFICATION: Remove complex boolean logic
+• SYNTAX CHECK: Avoid parentheses () in queries  
+• RETRY STRATEGY: Try single keywords instead of complex queries`;
+            }
+            else if (errorMessage.includes('API') ||
+                errorMessage.includes('rate')) {
+                errorType = 'api-limit';
+                specificSuggestions = `
+🔧 API LIMIT SOLUTIONS:
+• REDUCE FREQUENCY: Wait before retrying
+• SIMPLIFY QUERIES: Use fewer boolean operators
+• SCOPE NARROWING: Add owner/repo parameters`;
+            }
+            else if (errorMessage.includes('syntax') ||
+                errorMessage.includes('invalid')) {
+                errorType = 'syntax-error';
+                specificSuggestions = `
+🔧 SYNTAX ERROR SOLUTIONS:
+• REMOVE PARENTHESES: GitHub API doesn't support () grouping
+• SIMPLIFY BOOLEAN: Use "term1 OR term2" not "(term1 OR term2)"
+• CHECK OPERATORS: Only AND, OR, NOT are supported`;
+            }
+            let fallbackSuggestions = `
+🔄 INTELLIGENT FALLBACK STRATEGIES:
+• PROGRESSIVE SIMPLIFICATION: Start with single terms, add complexity gradually
+• BOOLEAN BASICS: "term1 OR term2" works, "(term1 OR term2) AND term3" doesn't
+• EXCLUDE NOISE: Add "NOT test NOT spec NOT mock" to focus on production code
+• REMOVE FILTERS: Try without path/language filters first
+• REPOSITORY TARGETING: Use owner/repo for focused searches${specificSuggestions}`;
+            // Add pattern-specific fallback suggestions
+            const query = args.query.toLowerCase();
+            if (query.includes('react')) {
+                fallbackSuggestions += `\n• REACT SPECIFIC: Try "useState OR useEffect", avoid complex hook combinations`;
+            }
+            if (query.includes('auth')) {
+                fallbackSuggestions += `\n• AUTH SPECIFIC: Try "login OR authenticate OR signin NOT test"`;
+            }
+            if (query.includes('api')) {
+                fallbackSuggestions += `\n• API SPECIFIC: Try "fetch OR axios OR request NOT mock"`;
+            }
+            // Add the attempted queries for debugging
+            fallbackSuggestions += `\n\n🔍 DEBUGGING INFO:
+• Original Query: "${args.query}"
+• Error Type: ${errorType}
+• Error Message: ${errorMessage}`;
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `GitHub Code Search Failed: ${errorMessage}${fallbackSuggestions}`,
+                        text: `🚨 GitHub Code Search Failed: ${errorMessage}${fallbackSuggestions}`,
                     },
                 ],
                 isError: true,
@@ -1370,6 +2267,276 @@ If you're looking for similar repositories, try:
     });
 }
 
+// Cross-Tool Orchestration Chains
+const TOOL_FALLBACK_CHAINS = {
+    'package-discovery': [
+        { tool: TOOL_NAMES.NPM_SEARCH_PACKAGES, reason: 'Primary package search' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_TOPICS,
+            reason: 'Ecosystem terminology discovery',
+        },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_REPOS,
+            reason: 'Repository-based discovery',
+        },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+            reason: 'Code implementation search',
+        },
+    ],
+    'code-discovery': [
+        { tool: TOOL_NAMES.GITHUB_SEARCH_CODE, reason: 'Direct code search' },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_REPOS, reason: 'Project-level discovery' },
+        { tool: TOOL_NAMES.NPM_SEARCH_PACKAGES, reason: 'Package-based solutions' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+            reason: 'Problem discussion search',
+        },
+    ],
+    'repository-discovery': [
+        { tool: TOOL_NAMES.NPM_GET_REPOSITORY, reason: 'Package-to-repo mapping' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_REPOS,
+            reason: 'Direct repository search',
+        },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_TOPICS, reason: 'Topic-based discovery' },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_USERS, reason: 'Organization discovery' },
+    ],
+    'issue-discovery': [
+        { tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES, reason: 'Primary issue search' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
+            reason: 'Solution implementation search',
+        },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_CODE, reason: 'Code example search' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_REPOS,
+            reason: 'Related project discovery',
+        },
+    ],
+    'user-discovery': [
+        { tool: TOOL_NAMES.GITHUB_SEARCH_USERS, reason: 'Primary user search' },
+        {
+            tool: TOOL_NAMES.GITHUB_GET_USER_ORGS,
+            reason: 'Organization membership discovery',
+        },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_REPOS, reason: 'User project discovery' },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_CODE, reason: 'Contribution analysis' },
+    ],
+};
+// Query Simplification Utilities
+class QueryOptimizer {
+    static getProgressiveQueries(originalQuery) {
+        const queries = [];
+        // Original query
+        queries.push(originalQuery);
+        // Remove special characters and clean up
+        const cleaned = originalQuery.replace(/[^\w\s-]/g, ' ').trim();
+        if (cleaned !== originalQuery) {
+            queries.push(cleaned);
+        }
+        // Extract key terms (remove common words)
+        const stopWords = [
+            'the',
+            'a',
+            'an',
+            'and',
+            'or',
+            'but',
+            'in',
+            'on',
+            'at',
+            'to',
+            'for',
+            'of',
+            'with',
+            'by',
+        ];
+        const terms = cleaned
+            .split(/\s+/)
+            .filter(term => term.length > 2 && !stopWords.includes(term.toLowerCase()));
+        // Multiple key terms
+        if (terms.length >= 2) {
+            queries.push(terms.slice(0, 2).join(' '));
+        }
+        // Single most important term
+        if (terms.length >= 1) {
+            queries.push(terms[0]);
+        }
+        // Remove duplicates and return
+        return [...new Set(queries)];
+    }
+    static simplifyPackageName(packageName) {
+        const variations = [packageName];
+        // Remove scope if present
+        if (packageName.startsWith('@')) {
+            const withoutScope = packageName.split('/')[1];
+            if (withoutScope) {
+                variations.push(withoutScope);
+            }
+        }
+        // Remove common suffixes
+        const suffixes = ['-js', '-node', '-lib', '-tool', '-cli', '-api'];
+        suffixes.forEach(suffix => {
+            if (packageName.endsWith(suffix)) {
+                variations.push(packageName.slice(0, -suffix.length));
+            }
+        });
+        return [...new Set(variations)];
+    }
+}
+// Context Analysis
+class ContextAnalyzer {
+    static analyzeQuery(query) {
+        const lowerQuery = query.toLowerCase();
+        const keywords = query.split(/\s+/).filter(term => term.length > 2);
+        // Determine query type
+        let type = 'general';
+        if (lowerQuery.includes('npm') ||
+            lowerQuery.includes('package') ||
+            lowerQuery.includes('install')) {
+            type = 'package';
+        }
+        else if (lowerQuery.includes('function') ||
+            lowerQuery.includes('class') ||
+            lowerQuery.includes('import')) {
+            type = 'code';
+        }
+        else if (lowerQuery.includes('repo') ||
+            lowerQuery.includes('project') ||
+            lowerQuery.includes('github')) {
+            type = 'repository';
+        }
+        else if (lowerQuery.includes('bug') ||
+            lowerQuery.includes('issue') ||
+            lowerQuery.includes('problem')) {
+            type = 'issue';
+        }
+        else if (lowerQuery.includes('user') ||
+            lowerQuery.includes('developer') ||
+            lowerQuery.includes('maintainer')) {
+            type = 'user';
+        }
+        // Determine complexity
+        const complexity = keywords.length <= 1
+            ? 'simple'
+            : keywords.length <= 3
+                ? 'medium'
+                : 'complex';
+        // Generate suggestions
+        const suggestions = [];
+        if (complexity === 'complex') {
+            suggestions.push('Try breaking down into simpler terms');
+            suggestions.push('Use 1-2 key words instead of full phrases');
+        }
+        return { type, keywords, complexity, suggestions };
+    }
+    static getToolChain(queryType) {
+        const chainKey = `${queryType}-discovery`;
+        return (TOOL_FALLBACK_CHAINS[chainKey] ||
+            TOOL_FALLBACK_CHAINS['package-discovery']);
+    }
+}
+// Enhanced Error Recovery
+function generateSmartRecovery(options) {
+    const { tool, query, packageName, resultCount, error } = options;
+    const queryAnalysis = query ? ContextAnalyzer.analyzeQuery(query) : null;
+    const simplifiedQueries = query
+        ? QueryOptimizer.getProgressiveQueries(query)
+        : [];
+    const packageVariations = packageName
+        ? QueryOptimizer.simplifyPackageName(packageName)
+        : [];
+    // Determine appropriate tool chain
+    const toolChain = queryAnalysis
+        ? ContextAnalyzer.getToolChain(queryAnalysis.type)
+        : TOOL_FALLBACK_CHAINS['package-discovery'];
+    // Build comprehensive recovery message
+    let recoveryText = `${tool} failed: ${error.message}`;
+    // Context-specific analysis
+    if (queryAnalysis) {
+        recoveryText += `
+
+🔍 QUERY ANALYSIS:
+• Type: ${queryAnalysis.type.toUpperCase()} search
+• Complexity: ${queryAnalysis.complexity.toUpperCase()}
+• Keywords: ${queryAnalysis.keywords.join(', ')}`;
+        if (queryAnalysis.suggestions.length > 0) {
+            recoveryText += `
+• Suggestions: ${queryAnalysis.suggestions.join(', ')}`;
+        }
+    }
+    // Query simplification suggestions
+    if (simplifiedQueries.length > 1) {
+        recoveryText += `
+
+🔄 SIMPLIFIED QUERY OPTIONS:
+${simplifiedQueries
+            .slice(1)
+            .map((q, i) => `${i + 1}. "${q}"`)
+            .join('\n')}`;
+    }
+    // Package name variations
+    if (packageVariations.length > 1) {
+        recoveryText += `
+
+📦 PACKAGE NAME VARIATIONS:
+${packageVariations
+            .slice(1)
+            .map((v, i) => `${i + 1}. "${v}"`)
+            .join('\n')}`;
+    }
+    // Cross-tool recommendations
+    recoveryText += `
+
+🔗 ALTERNATIVE TOOL CHAIN:
+${toolChain.map((t, i) => `${i + 1}. ${t.tool} - ${t.reason}`).join('\n')}`;
+    // Specific error type handling
+    if (error.message.includes('404') || error.message.includes('not found')) {
+        recoveryText += `
+
+💡 NOT FOUND RECOVERY:
+• Check spelling and exact names
+• Try search tools instead of direct access
+• Use broader discovery methods first`;
+    }
+    if (error.message.includes('API') || error.message.includes('rate limit')) {
+        recoveryText += `
+
+⏱️ API LIMIT RECOVERY:
+• Wait a moment before retrying
+• Use simpler queries to reduce API usage
+• Try different tools that may use different API endpoints`;
+    }
+    // General best practices
+    recoveryText += `
+
+📋 PROVEN RECOVERY WORKFLOW:
+1. Start with search tools (npm_search_packages, github_search_repos)
+2. Use discovery results to guide specific tool usage
+3. Progressively simplify queries if needed
+4. Try alternative tool chains for different perspectives`;
+    // Context-specific recommendations
+    if (resultCount === 0) {
+        recoveryText += `
+
+🎯 ZERO RESULTS STRATEGY:
+• Broaden search terms
+• Remove restrictive filters
+• Try ecosystem discovery tools
+• Use single keywords instead of phrases`;
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: recoveryText,
+            },
+        ],
+        isError: true,
+    };
+}
+
 function registerViewRepositoryTool(server) {
     server.tool(TOOL_NAMES.GITHUB_GET_REPOSITORY, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_REPOSITORY], {
         owner: z
@@ -1389,15 +2556,12 @@ function registerViewRepositoryTool(server) {
             return await viewGitHubRepositoryInfo(args);
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to view repository: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Repository View',
+                owner: args.owner,
+                repo: args.repo,
+                error: error,
+            });
         }
     });
 }
@@ -2244,18 +3408,69 @@ function registerSearchGitHubPullRequestsTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubPullRequests(args);
+            const result = await searchGitHubPullRequests(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO RESULTS RECOVERY STRATEGY:
+• Try broader terms: "${args.query}" → "fix", "feature", "update"
+• Implementation search: github_search_code for actual code changes
+• Project discovery: github_search_repos for related projects
+• Issue tracking: github_search_issues for related problems
+
+💡 PR SEARCH OPTIMIZATION:
+• Focus on action words: "implement", "add", "fix", "update"
+• Try state filters: state=open vs state=closed
+• Use review filters: draft=false for completed PRs
+
+🔗 RECOMMENDED TOOL CHAIN:
+1. github_search_issues - Find problems that needed solutions
+2. github_search_code - See actual implementation patterns
+3. github_search_repos - Discover projects with similar features`;
+                }
+                else if (resultCount <= 5) {
+                    responseText += `
+
+💡 FEW RESULTS ENHANCEMENT:
+• Found ${resultCount} PRs - try removing restrictive filters
+• Alternative: github_search_code for implementation examples
+• Cross-reference: github_search_issues for related discussions`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub pull requests: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Pull Requests Search',
+                query: args.query,
+                owner: args.owner,
+                repo: args.repo,
+                error: error,
+            });
         }
     });
 }
@@ -2387,6 +3602,39 @@ async function npmSearch(args) {
     }
 }
 
+// Analyze NPM search patterns and suggest fallbacks
+function analyzeNpmSearchPattern(args) {
+    const suggestions = [];
+    const fallbackStrategy = [];
+    const organizationalHints = [];
+    let patternType = 'basic';
+    const query = args.query.toLowerCase();
+    // Detect organizational packages
+    if (query.includes('@') ||
+        query.includes('internal') ||
+        query.includes('private')) {
+        patternType = 'organizational';
+        organizationalHints.push('ORGANIZATIONAL PACKAGE DETECTED: Consider checking GitHub organizations first');
+        fallbackStrategy.push(`Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} to discover private package access`);
+    }
+    // Complex search patterns
+    if (query.split(' ').length > 2) {
+        patternType = 'complex-multi-term';
+        suggestions.push('PROVEN: Complex phrases often yield zero results - try single terms');
+        fallbackStrategy.push('Break down into primary term → secondary filters');
+    }
+    // Technology-specific patterns
+    if (query.includes('react') ||
+        query.includes('vue') ||
+        query.includes('angular')) {
+        patternType = 'framework-specific';
+        suggestions.push('FRAMEWORK DETECTED: Consider ecosystem-specific searches');
+        fallbackStrategy.push(`Use ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} for framework ecosystem discovery`);
+    }
+    // Generic fallback strategy for all patterns
+    fallbackStrategy.push(`1. ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Search ecosystem terms`, `2. ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Find repositories that might be packages`, `3. ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Search package.json files`, `4. ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Search package development history`, `5. ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Search package mentions in PRs`, `6. ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Search package discussions`);
+    return { patternType, suggestions, fallbackStrategy, organizationalHints };
+}
 function registerNpmSearchTool(server) {
     server.tool(TOOL_NAMES.NPM_SEARCH_PACKAGES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_SEARCH_PACKAGES], {
         query: z
@@ -2410,19 +3658,111 @@ function registerNpmSearchTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await npmSearch(args);
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search npm packages: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
+            // Analyze search pattern for insights and fallbacks
+            const patternAnalysis = analyzeNpmSearchPattern(args);
+            const result = await npmSearch(args);
+            // Check if we got poor results and enhance with fallback suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                // Parse result to check quality
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.results && Array.isArray(parsed.results)) {
+                        resultCount = parsed.results.length;
+                    }
+                }
+                catch {
+                    // If not JSON, try to estimate from text
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5); // Rough estimate
+                }
+                // Add organizational hints if detected
+                if (patternAnalysis.organizationalHints.length > 0) {
+                    responseText += `\n\n🏢 ORGANIZATIONAL PACKAGE INSIGHTS:`;
+                    patternAnalysis.organizationalHints.forEach(hint => {
+                        responseText += `\n• ${hint}`;
+                    });
+                }
+                // Add pattern-specific suggestions
+                if (patternAnalysis.suggestions.length > 0) {
+                    responseText += `\n\n💡 SEARCH PATTERN INSIGHTS (${patternAnalysis.patternType.toUpperCase()}):`;
+                    patternAnalysis.suggestions.forEach(suggestion => {
+                        responseText += `\n• ${suggestion}`;
+                    });
+                }
+                // Add fallback strategy if results are poor (< 5 results or specific patterns)
+                if (resultCount < 5 || patternAnalysis.patternType !== 'basic') {
+                    responseText += `\n\n🔄 NPM SEARCH FALLBACK STRATEGY:`;
+                    responseText += `\nIf NPM search yields insufficient results, try this validated workflow:`;
+                    patternAnalysis.fallbackStrategy.forEach((step, index) => {
+                        responseText += `\n${index + 1}. ${step}`;
+                    });
+                }
+                // Add general best practices
+                responseText += `\n\n📋 NPM SEARCH BEST PRACTICES:`;
+                responseText += `\n• Single terms work best: "react", "auth", "cli"`;
+                responseText += `\n• Combined terms: "react-hooks", "typescript-cli"`;
+                responseText += `\n• Avoid complex phrases: Break "react auth jwt library" → "react" + "auth"`;
+                responseText += `\n• Organizational packages: @company/ triggers private search workflow`;
+                responseText += `\n• 0 results → broader terms, 1-20 IDEAL, 100+ → more specific`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            // Enhanced error handling with fallback suggestions
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const fallbackSuggestions = `
+🔄 NPM SEARCH FALLBACK WORKFLOW:
+When NPM registry search fails, try this proven sequence:
+
+1. ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Discover ecosystem terminology
+   • Use broader terms: "authentication" instead of "jwt-auth-library"
+   • Find related technologies and packages
+
+2. ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Find package repositories
+   • Search for repositories that might contain packages
+   • Look for package.json indicators
+
+3. ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Search package manifests
+   • Query: "package.json" + your terms
+   • Find actual package definitions
+
+4. ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Development history
+   • Search commit messages for package development
+   • Find package creation/updates
+
+5. ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Package discussions
+   • Find PRs mentioning package development
+   • Discover package features and issues
+
+6. ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Community discussions
+   • Find issues discussing packages
+   • Discover alternatives and recommendations
+
+💡 PROVEN STRATEGIES:
+• Try simpler terms if complex search fails
+• Check organizational access for @company/ packages  
+• Use GitHub ecosystem discovery when NPM fails`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `NPM Search Failed: ${errorMessage}${fallbackSuggestions}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
     });
 }
 
@@ -2796,18 +4136,71 @@ function registerSearchGitHubIssuesTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubIssues(args);
+            const result = await searchGitHubIssues(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    // If parsing fails, estimate from text
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                // Add smart suggestions for empty or poor results
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO RESULTS RECOVERY STRATEGY:
+• Try broader terms: "${args.query}" → single keywords
+• Alternative discovery: github_search_repos for related projects
+• Problem context: github_search_code for implementation examples
+• Solution tracking: github_search_pull_requests for fixes
+
+💡 QUERY SIMPLIFICATION:
+• Remove quotes and special characters
+• Use single keywords: "bug", "error", "feature"
+• Try related terms: "issue" → "problem", "bug" → "error"
+
+🔗 RECOMMENDED TOOL CHAIN:
+1. github_search_repos - Find projects that might have similar issues
+2. github_search_code - Search for code patterns related to your problem
+3. npm_search_packages - Find packages that solve similar problems`;
+                }
+                else if (resultCount <= 5) {
+                    responseText += `
+
+💡 FEW RESULTS ENHANCEMENT:
+• Found ${resultCount} issues - try broader search terms
+• Alternative: github_search_repos for project-level discovery
+• Cross-reference: github_search_code for implementation patterns`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub issues: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Issues Search',
+                query: args.query,
+                owner: args.owner,
+                repo: args.repo,
+                error: error,
+            });
         }
     });
 }
@@ -2924,18 +4317,67 @@ function registerSearchGitHubTopicsTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubTopics(args);
+            const result = await searchGitHubTopics(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO TOPICS FOUND RECOVERY:
+• Try simpler terms: "${args.query}" → single technology keywords
+• Ecosystem discovery: npm_search_packages for related packages
+• Repository search: github_search_repos for projects using these topics
+• User community: github_search_users for topic experts
+
+💡 TOPIC SEARCH OPTIMIZATION:
+• Use popular technology terms: "react", "javascript", "python"
+• Try compound topics: "machine-learning", "web-development"
+• Focus on featured topics: featured=true
+
+🔗 RECOMMENDED DISCOVERY CHAIN:
+1. npm_search_packages - Find packages in this domain
+2. github_search_repos - Discover projects using these topics
+3. github_search_code - Find implementations using topic technologies`;
+                }
+                else if (resultCount <= 3) {
+                    responseText += `
+
+💡 LIMITED TOPICS ENHANCEMENT:
+• Found ${resultCount} topics - try broader or more popular terms
+• Ecosystem expansion: npm_search_packages for related technologies
+• Project discovery: github_search_repos for topic implementation`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub topics: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Topics Search',
+                query: args.query,
+                error: error,
+            });
         }
     });
 }
@@ -3068,18 +4510,67 @@ function registerSearchGitHubUsersTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubUsers(args);
+            const result = await searchGitHubUsers(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO RESULTS RECOVERY STRATEGY:
+• Try simpler terms: "${args.query}" → technology keywords only
+• Organization discovery: github_get_user_organizations for company access
+• Project-based search: github_search_repos to find user projects
+• Code contribution search: github_search_code for user activity
+
+💡 USER SEARCH OPTIMIZATION:
+• Use technology terms: "react", "python", "javascript"
+• Try location filters: location="San Francisco", location="Remote"
+• Focus on active users: followers>10, repos>5
+
+🔗 RECOMMENDED TOOL CHAIN:
+1. github_search_repos - Find projects by technology/topic
+2. github_get_user_organizations - Discover organizations
+3. npm_search_packages - Find package maintainers`;
+                }
+                else if (resultCount <= 5) {
+                    responseText += `
+
+💡 FEW RESULTS ENHANCEMENT:
+• Found ${resultCount} users - try broader location or technology terms
+• Alternative: github_search_repos for project discovery
+• Organization search: github_get_user_organizations`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub users: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Users Search',
+                query: args.query,
+                error: error,
+            });
         }
     });
 }
@@ -3210,6 +4701,325 @@ function registerNpmDependencyAnalysisTool(server) {
     });
 }
 
+async function checkGitHubAuth() {
+    try {
+        const authResult = await executeGitHubCommand('auth', ['status'], {
+            timeout: 10000,
+            cache: false,
+        });
+        if (authResult.isError) {
+            const errorText = String(authResult.content[0]?.text || '');
+            if (errorText.includes('not logged into') ||
+                errorText.includes('not authenticated')) {
+                return {
+                    status: 'not_authenticated',
+                    message: 'Not logged into GitHub CLI. Please run: gh auth login',
+                };
+            }
+            return {
+                status: 'error',
+                message: `GitHub CLI error: ${errorText}`,
+            };
+        }
+        const statusText = String(authResult.content[0]?.text || '');
+        // Extract username if present
+        const userMatch = statusText.match(/Logged in to github\.com as ([^\s]+)/);
+        const user = userMatch ? userMatch[1] : undefined;
+        if (statusText.includes('Logged in to github.com')) {
+            return {
+                status: 'authenticated',
+                user,
+                message: user ? `Authenticated as ${user}` : 'Authenticated to GitHub',
+            };
+        }
+        return {
+            status: 'not_authenticated',
+            message: 'GitHub CLI authentication status unclear. Please run: gh auth login',
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            message: `Failed to check GitHub auth: ${error.message}`,
+        };
+    }
+}
+async function checkNpmConnectivity() {
+    try {
+        const pingResult = await executeNpmCommand('ping', [], {
+            timeout: 10000,
+            cache: false,
+        });
+        if (pingResult.isError) {
+            const errorText = String(pingResult.content[0]?.text || '');
+            return {
+                status: 'disconnected',
+                message: `NPM registry unreachable: ${errorText}`,
+            };
+        }
+        const pingText = String(pingResult.content[0]?.text || '');
+        if (pingText.includes('npm ping ok') || pingText.includes('Ping success')) {
+            // Extract registry if present
+            const registryMatch = pingText.match(/registry: (.+)/);
+            const registry = registryMatch
+                ? registryMatch[1]
+                : 'https://registry.npmjs.org';
+            return {
+                status: 'connected',
+                registry,
+                message: `Connected to NPM registry: ${registry}`,
+            };
+        }
+        return {
+            status: 'error',
+            message: `NPM ping response unclear: ${pingText}`,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            message: `Failed to ping NPM registry: ${error.message}`,
+        };
+    }
+}
+async function checkGitHubRateLimits() {
+    try {
+        const rateLimitResult = await executeGitHubCommand('api', ['rate_limit'], {
+            timeout: 10000,
+            cache: false,
+        });
+        if (rateLimitResult.isError) {
+            const errorText = String(rateLimitResult.content[0]?.text || '');
+            return {
+                status: 'error',
+                primary_api: {
+                    remaining: 0,
+                    limit: 0,
+                    reset_time: '',
+                    usage_percentage: 100,
+                },
+                search_api: {
+                    remaining: 0,
+                    limit: 0,
+                    reset_time: '',
+                    usage_percentage: 100,
+                },
+                code_search: {
+                    remaining: 0,
+                    limit: 0,
+                    reset_time: '',
+                    usage_percentage: 100,
+                },
+                message: `Failed to fetch rate limits: ${errorText}`,
+                recommendations: [
+                    'GitHub authentication may be required',
+                    'Run: gh auth login',
+                ],
+            };
+        }
+        const content = String(rateLimitResult.content[0]?.text || '');
+        if (!content) {
+            throw new Error('No rate limit data received');
+        }
+        let rateLimit;
+        try {
+            const parsed = JSON.parse(content);
+            rateLimit = parsed.result || parsed;
+        }
+        catch {
+            rateLimit = JSON.parse(content);
+        }
+        const formatResetTime = (reset) => new Date(reset * 1000).toISOString();
+        const calculateUsage = (used, limit) => Math.round((used / limit) * 100);
+        const core = rateLimit.resources.core;
+        const search = rateLimit.resources.search;
+        const codeSearch = rateLimit.resources.code_search;
+        const primaryApi = {
+            remaining: core.remaining,
+            limit: core.limit,
+            reset_time: formatResetTime(core.reset),
+            usage_percentage: calculateUsage(core.used, core.limit),
+        };
+        const searchApi = {
+            remaining: search.remaining,
+            limit: search.limit,
+            reset_time: formatResetTime(search.reset),
+            usage_percentage: calculateUsage(search.used, search.limit),
+        };
+        const codeSearchApi = {
+            remaining: codeSearch.remaining,
+            limit: codeSearch.limit,
+            reset_time: formatResetTime(codeSearch.reset),
+            usage_percentage: calculateUsage(codeSearch.used, codeSearch.limit),
+        };
+        // Determine overall status
+        const minRemaining = Math.min(core.remaining, search.remaining, codeSearch.remaining);
+        let status;
+        const recommendations = [];
+        if (minRemaining === 0) {
+            status = 'exhausted';
+            recommendations.push('🚨 API limits exhausted - wait for reset or use alternative approaches');
+            recommendations.push('Consider using cached data or reducing API calls');
+        }
+        else if (minRemaining < 10) {
+            status = 'limited';
+            recommendations.push('⚠️ API limits low - prioritize essential requests only');
+            recommendations.push('Avoid extensive searches or bulk operations');
+        }
+        else {
+            status = 'healthy';
+            recommendations.push('✅ All APIs ready for normal operation');
+        }
+        // Add specific API recommendations
+        if (codeSearch.remaining < 5) {
+            recommendations.push('🔍 Code search severely limited - use repository-specific searches');
+        }
+        if (search.remaining < 10) {
+            recommendations.push('🔎 Search API limited - reduce search complexity');
+        }
+        if (core.remaining < 100) {
+            recommendations.push('🏠 Core API limited - avoid bulk repository operations');
+        }
+        return {
+            status,
+            primary_api: primaryApi,
+            search_api: searchApi,
+            code_search: codeSearchApi,
+            message: `Rate limits checked - ${status}`,
+            recommendations,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            primary_api: {
+                remaining: 0,
+                limit: 0,
+                reset_time: '',
+                usage_percentage: 100,
+            },
+            search_api: {
+                remaining: 0,
+                limit: 0,
+                reset_time: '',
+                usage_percentage: 100,
+            },
+            code_search: {
+                remaining: 0,
+                limit: 0,
+                reset_time: '',
+                usage_percentage: 100,
+            },
+            message: `Error checking rate limits: ${error.message}`,
+            recommendations: [
+                'Unable to determine API status',
+                'Check GitHub authentication',
+            ],
+        };
+    }
+}
+async function performApiStatusCheck() {
+    try {
+        console.log('🔍 Performing comprehensive API status check...');
+        // Perform all checks in parallel for efficiency
+        const [githubAuth, npmConnectivity, githubRateLimits] = await Promise.all([
+            checkGitHubAuth(),
+            checkNpmConnectivity(),
+            checkGitHubRateLimits(),
+        ]);
+        // Determine overall status
+        let overallStatus;
+        const researchRecommendations = [];
+        if (githubAuth.status !== 'authenticated') {
+            overallStatus = 'not_ready';
+            researchRecommendations.push('❌ GitHub authentication required before research');
+            researchRecommendations.push('Run: gh auth login');
+        }
+        else if (npmConnectivity.status !== 'connected') {
+            overallStatus = 'limited';
+            researchRecommendations.push('⚠️ NPM unavailable - GitHub research only');
+        }
+        else if (githubRateLimits.status === 'exhausted') {
+            overallStatus = 'not_ready';
+            researchRecommendations.push('❌ GitHub API exhausted - wait for reset');
+            researchRecommendations.push(`Next reset: ${githubRateLimits.code_search.reset_time}`);
+        }
+        else if (githubRateLimits.status === 'limited') {
+            overallStatus = 'limited';
+            researchRecommendations.push('⚠️ Limited API quota - reduce research scope');
+            researchRecommendations.push('Use targeted searches instead of broad exploration');
+        }
+        else {
+            overallStatus = 'ready';
+            researchRecommendations.push('✅ All systems ready for comprehensive research');
+            researchRecommendations.push('NPM package discovery and GitHub analysis available');
+        }
+        // Add research strategy recommendations based on API limits
+        if (githubRateLimits.code_search.remaining < 5) {
+            researchRecommendations.push('🔍 Code search critical - use repository browsing instead');
+        }
+        if (githubRateLimits.search_api.remaining < 20) {
+            researchRecommendations.push('🔎 Search API limited - focus on specific repositories');
+        }
+        if (githubRateLimits.primary_api.remaining < 200) {
+            researchRecommendations.push('🏠 Core API limited - minimize repository exploration');
+        }
+        const result = {
+            github_auth: githubAuth,
+            npm_connectivity: npmConnectivity,
+            github_rate_limits: githubRateLimits,
+            overall_status: overallStatus,
+            research_recommendations: researchRecommendations,
+            timestamp: new Date().toISOString(),
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `🚨 API Status Check Failed: ${error.message}
+
+🔧 Troubleshooting Steps:
+1. Check GitHub CLI installation: gh --version
+2. Check NPM installation: npm --version  
+3. Check network connectivity
+4. Try: gh auth login
+5. Try: npm ping
+
+💡 Manual Verification:
+- GitHub Auth: gh auth status
+- NPM Registry: npm ping
+- GitHub API: gh api rate_limit`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function registerApiStatusCheckTool(server) {
+    server.tool(TOOL_NAMES.API_STATUS_CHECK, TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK], {
+    // No parameters needed for status check
+    }, {
+        title: 'API Status Check',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => {
+        return await performApiStatusCheck();
+    });
+}
+
 async function npmGetRepository(packageName) {
     const cacheKey = generateCacheKey('npm-get-repository', { packageName });
     return withCache(cacheKey, async () => {
@@ -3255,15 +5065,22 @@ function registerNpmGetRepositoryTool(server) {
             return await npmGetRepository(args.packageName);
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to get npm repository info: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            const errorMessage = error.message;
+            // Enhanced error handling for package not found
+            if (errorMessage.includes('404') ||
+                errorMessage.includes('not found')) {
+                return generateSmartRecovery({
+                    tool: 'NPM Get Repository',
+                    packageName: args.packageName,
+                    error: error,
+                });
+            }
+            // Generic enhanced error handling
+            return generateSmartRecovery({
+                tool: 'NPM Get Repository',
+                packageName: args.packageName,
+                error: error,
+            });
         }
     });
 }
@@ -3313,15 +5130,11 @@ function registerNpmGetDependenciesTool(server) {
             return await npmGetDependencies(args.packageName);
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to get npm dependencies: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'NPM Get Dependencies',
+                packageName: args.packageName,
+                error: error,
+            });
         }
     });
 }
@@ -4061,132 +5874,6 @@ function registerGithubStatusResource(server) {
     });
 }
 
-function registerGithubRateLimitResource(server) {
-    server.resource('github-rate-limits', 'github://rate-limits', async (uri) => {
-        try {
-            // Use safe GitHub command execution for API calls
-            const rateLimitResult = await executeGitHubCommand('api', ['rate_limit'], {
-                timeout: 10000,
-                cache: false,
-            });
-            if (rateLimitResult.isError) {
-                const errorText = String(rateLimitResult.content[0]?.text || 'Failed to fetch rate limits');
-                throw new Error(errorText);
-            }
-            // Extract and parse the rate limit data
-            const content = String(rateLimitResult.content[0]?.text || '');
-            if (!content) {
-                throw new Error('No rate limit data received');
-            }
-            let rateLimit;
-            try {
-                const parsed = JSON.parse(content);
-                rateLimit = parsed.result || parsed;
-            }
-            catch {
-                rateLimit = JSON.parse(content);
-            }
-            const rateLimitInfo = processRateLimit(rateLimit);
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        mimeType: 'application/json',
-                        text: JSON.stringify({
-                            status: 'GitHub API Rate Limits - LIVE STATUS',
-                            description: 'Real-time GitHub API rate limit status for all endpoints',
-                            rate_limits: rateLimitInfo,
-                            usage_notes: {
-                                primary_api: 'Used for most GitHub operations (repos, issues, PRs, etc.)',
-                                search_api: 'Used for searching repositories, code, issues, users',
-                                code_search: 'Dedicated endpoint for code search operations (most restrictive)',
-                                graphql_api: 'Used for GraphQL queries',
-                                status_meanings: {
-                                    healthy: 'All APIs have sufficient remaining requests',
-                                    limited: 'Some APIs are running low on requests (< 10 remaining)',
-                                    exhausted: 'One or more APIs have no remaining requests',
-                                },
-                            },
-                            recommendations: {
-                                healthy: 'All APIs ready for use',
-                                limited: 'Consider prioritizing essential requests only',
-                                exhausted: 'Wait until reset time or use alternative approaches',
-                            },
-                            timestamp: new Date().toISOString(),
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        mimeType: 'application/json',
-                        text: JSON.stringify({
-                            status: 'GitHub API Rate Limits - ERROR',
-                            error: error.message,
-                            message: 'Unable to check rate limits - authentication may be required',
-                            timestamp: new Date().toISOString(),
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-    });
-}
-function processRateLimit(rateLimit) {
-    const formatResetTime = (reset) => new Date(reset * 1000).toISOString();
-    const calculateUsage = (used, limit) => Math.round((used / limit) * 100);
-    const core = rateLimit.resources.core;
-    const search = rateLimit.resources.search;
-    const codeSearch = rateLimit.resources.code_search;
-    const graphql = rateLimit.resources.graphql;
-    // Determine overall status based on most restrictive API
-    const minRemaining = Math.min(core.remaining, search.remaining, codeSearch.remaining, graphql.remaining);
-    let status;
-    if (minRemaining === 0) {
-        status = 'exhausted';
-    }
-    else if (minRemaining < 10) {
-        status = 'limited';
-    }
-    else {
-        status = 'healthy';
-    }
-    // Find the earliest reset time
-    const nextReset = Math.min(core.reset, search.reset, codeSearch.reset, graphql.reset);
-    return {
-        primary_api: {
-            remaining: core.remaining,
-            limit: core.limit,
-            reset_time: formatResetTime(core.reset),
-            usage_percentage: calculateUsage(core.used, core.limit),
-        },
-        search_api: {
-            remaining: search.remaining,
-            limit: search.limit,
-            reset_time: formatResetTime(search.reset),
-            usage_percentage: calculateUsage(search.used, search.limit),
-        },
-        code_search: {
-            remaining: codeSearch.remaining,
-            limit: codeSearch.limit,
-            reset_time: formatResetTime(codeSearch.reset),
-            usage_percentage: calculateUsage(codeSearch.used, codeSearch.limit),
-        },
-        graphql_api: {
-            remaining: graphql.remaining,
-            limit: graphql.limit,
-            reset_time: formatResetTime(graphql.reset),
-            usage_percentage: calculateUsage(graphql.used, graphql.limit),
-        },
-        status,
-        next_reset: formatResetTime(nextReset),
-    };
-}
-
 // Sanitize output to remove potential tokens
 function sanitizeOutput(output) {
     if (!output)
@@ -4627,6 +6314,8 @@ process.stdin.on('close', async () => {
 });
 // Register all tools
 function registerAllTools(server) {
+    // System & API Status - CRITICAL FIRST STEP
+    registerApiStatusCheckTool(server);
     registerGitHubSearchCodeTool(server);
     registerFetchGitHubFileContentTool(server);
     registerViewRepositoryTool(server);
@@ -4659,7 +6348,6 @@ function registerAllTools(server) {
 function registerResources(server) {
     registerUsageGuideResource(server);
     registerGithubStatusResource(server);
-    registerGithubRateLimitResource(server);
     registerNpmStatusResource(server);
     registerRepositoryIntelligenceResource(server);
 }