docs: restructure README following crafting-readme-files skill

Reorder to lead with value: hero (badges + curl) → TL;DR (feature table)
→ quick example with output → three outcomes → concepts → comparison table
→ install → CLI reference. Add missing sections: troubleshooting,
limitations, FAQ, comparison vs alternatives. Move JSON schema to
collapsible details block.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: saltmachine