docs: world-class README overhaul with competitive landscape, architecture diagrams, and technical deep dives

[OnlyTerp]

Summary

Complete rewrite of README.md from ~150 lines to ~565 lines. This is a documentation-only change — no code was modified.

Major additions:

• Header: Badges (arXiv, license, Python, PyTorch, CUDA) and navigation links
• "Why KV Cache Compression Matters": Memory scaling table showing the KV cache problem
• Expanded results: New context window extension table comparing KVTC vs TurboQuant vs FP16 baseline
• "How It Works": ASCII pipeline diagram, three-stage walkthrough (PCA → DP quantization → entropy coding), and key innovations table
• Quick Start: Requirements, install, benchmarks, basic usage, and calibration sections
• Full v4 benchmarks table and TurboQuant prefill throughput comparison
• "KV Cache Compression Landscape (April 2026)": Method comparison table (6 methods), quality-vs-compression chart, KVTC vs TurboQuant head-to-head, TriAttention analysis, and "What's Viral Right Now" section
• Architecture: Full project structure tree and detailed compression/decompression pipeline diagrams
• Technical Deep Dive: Collapsible FAQ sections (PCA vs rotation, DP allocation, K/V budgets, paper vs implementation)
• Roadmap: Completed / in-progress / planned items
• Contributing: High-impact areas table with difficulty/impact ratings
• Research Context: 5 ecosystem findings, 7 related papers, expanded BibTeX citation

Review & Testing Checklist for Human

• Verify numerical claims against actual benchmark data — The context window extension table lists KVTC K2V4 at "~1.4M tokens, ~65 tok/s" and K1V3 at "~2.1M, ~60 tok/s" marked "Integration in progress." Confirm these projections are reasonable and that the "integration in progress" qualifier is clear enough to readers.
• Spot-check external links — The landscape section references ~15 external URLs (arXiv papers, GitHub PRs/issues, blog posts). Key ones to verify: TurboQuant vLLM PR #39890, TriAttention repo, NexusQuant repo, KVPress repo. Broken links will hurt credibility.
• Review competitive claims for fairness — The KVTC vs TurboQuant table says KVTC achieves "cos 0.996 vs ~0.95 @ 6x." The ~0.95 figure for TurboQuant should be validated. The tone should position KVTC favorably without misrepresenting competitors.
• Verify code examples match actual API — Quick Start references KVTCCompressorFast, calibrate_model, CalibrationData, and specific method signatures. Confirm these match the current codebase.
• Check project structure listing — The Architecture section lists ~25 files. Verify no files are listed that don't exist (or important ones are missing).

Recommended test: Render the README on GitHub (or a local markdown previewer) and scan it in under 60 seconds — the key value prop, results, and quick start should be immediately clear. Check that all collapsible <details> sections expand correctly and that the ASCII diagrams render properly in a monospaced code block.

Notes

• The "What's Viral Right Now (Week of April 14, 2026)" section is inherently time-sensitive. Consider whether this should be moved to a separate doc (e.g., RESEARCH_NOTES.md) or updated periodically.
• The pip install -e . in Quick Start assumes setup.py is functional — worth a quick sanity check.
• BibTeX author field uses {\L}a{\'n}cucki for the Polish characters — this is standard LaTeX but verify it renders correctly in common citation managers.

Link to Devin session: https://app.devin.ai/sessions/e367c15ff93343faa5e821eb3babf465
Requested by: @OnlyTerp

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.