Add tweet ranking algorithm documentation and optimization guide

[Copilot]

Repository lacked user-facing documentation explaining how the ranking algorithm works and how to optimize content for it.

Documentation Added

• docs/TWEET_RANKING_GUIDE.md (796 lines) - Complete technical breakdown of the ranking pipeline:

  • 6-stage architecture: candidate generation → feature hydration → ML scoring → filtering → reranking → mixing
  • ~6,000 features per candidate (author, content, engagement, graph, temporal)
  • ML models: Heavy Ranker (Navi), Light Ranker, Phoenix scorer
  • In-network vs out-of-network handling (OON gets 0.75x penalty)
  • Practical optimization strategies for content creators
  • Implementation guide for building similar systems with code examples

• docs/RANKING_QUICK_REFERENCE.md (299 lines) - Concise reference:

  • Ranking signal impact table (likes/retweets/replies = high, "not interested" = very negative)
  • Best practices and anti-patterns
  • Minimal viable ranker implementation
  • Key metrics to track

• README.md - Added "Understanding Tweet Ranking" section with links to guides

Key Technical Details Documented

• Pipeline narrows ~1B tweets → ~100 shown via multi-stage filtering
• Candidate sources: Earlybird (in-network), UTEG (graph-based), TweetMixer (blended), FRS (follow recs)
• Feature systems: SimClusters, TwHIN embeddings, Real Graph, TweepCred
• Scoring uses multi-task neural networks predicting engagement probabilities
• Diversity filters enforce author balance, content variety, deduplication

Example of simplified ranker from guide:

def rank_content(user_id, candidates):
    scored = []
    for item in candidates:
        recency = 1.0 / (1 + hours_since_post(item))
        engagement = (item.likes + 2*item.retweets + 3*item.replies) / (1 + item.impressions)
        relevance = compute_relevance(user_id, item)
        
        score = 0.3*recency + 0.4*engagement + 0.3*relevance
        scored.append((item, score))
    
    scored.sort(key=lambda x: x[1], reverse=True)
    return [item for item, score in scored[:100]]

Targets two audiences: content creators optimizing for algorithmic reach, and engineers building recommendation systems.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.