Greptile Summary

This PR implements a sophisticated 12-tier search ranking system that dramatically improves application search accuracy. The ranking system prioritizes results in this order: pinned apps → exact matches → prefix matches → word-start matches → metadata matches → fuzzy matches. Within each tier, frecency scores (zoxide-style time-bucketed scoring) provide intelligent boosting based on usage patterns.

Key Implementation Details:

• Configurable prefix depth (prefix_depth config option, default 3 characters) controls when prefix matching takes priority over other match types
• 12 distinct ranking tiers ensure predictable, intuitive search results with pinned apps always appearing first
• Frecency integration applies time-bucketed multipliers (4x for <1 hour, 2x for <1 day, 0.5x for <1 week, 0.25x for older) with additive boosting (10x multiplier) that doesn't dominate exact/prefix matches
• Multi-field matching searches across app names, executable names, keywords, categories, and generic names
• Score breakdown tracking added for debugging with -T flag (includes detailed tier, matcher score, and frecency boost information)

Release Management Improvements:

• Introduced release/vX.Y.Z branch pattern for version management
• Allows dev branch to continue accepting PRs during release preparation
• Fully documented in PROJECT_STANDARDS.md and CONTRIBUTING.md

Code Quality:

• Removed unused Message enum variants (KeyInput, Mouse, TogglePin, Render, Resize)
• Removed unused MouseEventKind enum
• Removed unused FrecencyEntry::new() function
• Cleaned up unused imports
• Fixed import ordering in search.rs

Documentation:

• Comprehensive updates to README.md, USAGE.md, config.toml, and fsel.1 man page
• All documentation includes search ranking details and prefix_depth usage examples

All changes are backward compatible - existing configurations continue to work with sensible defaults.

Confidence Score: 5/5

• This PR is safe to merge with no critical issues found
• The implementation is well-structured with clear separation of concerns. The 12-tier ranking system uses sensible score ranges (100M+ for top tiers) that prevent score overflow. Frecency integration is properly balanced to enhance but not dominate explicit matches. Code cleanup removes genuinely unused code without affecting functionality. All changes are backward compatible with appropriate defaults. Documentation is comprehensive and accurate.
• No files require special attention

sequenceDiagram
    participant User
    participant CLI
    participant State
    participant Filter
    participant Matcher
    participant Frecency
    participant UI

    User->>CLI: Type search query
    CLI->>State: CharInput message
    State->>State: Update query string
    State->>Filter: filter()
    
    Filter->>Filter: Check if query empty
    alt Query is empty
        Filter->>State: Return all apps (original order)
    else Query has text
        Filter->>Matcher: Create nucleo matcher
        Filter->>Matcher: Parse search pattern
        
        loop For each app
            Filter->>Filter: Check exact matches (app/exec name)
            Filter->>Filter: Check prefix matches (app/exec name)
            Filter->>Filter: Check word-start matches (within prefix_depth)
            Filter->>Filter: Check metadata matches (keywords/categories)
            Filter->>Matcher: Calculate fuzzy match score
            Filter->>Filter: Determine ranking tier (1-12)
            
            alt App is pinned
                Filter->>Filter: Assign tier 1-8 (120M-20M range)
            else App is not pinned
                Filter->>Filter: Assign tier 9-12 (90M-0 range)
            end
            
            Filter->>Frecency: Get frecency score
            Frecency->>Frecency: Calculate time-bucketed multiplier
            Frecency->>Filter: Return frecency boost
            
            Filter->>Filter: final_score = bucket + (matcher*100) + (frec*10)
            Filter->>Filter: Create ScoreBreakdown
        end
        
        Filter->>Filter: Sort by final_score (desc), then name
        Filter->>State: Return ranked results
    end
    
    State->>State: Reset selection to first item
    State->>UI: Trigger render with ranked apps
    UI->>User: Display search results