docs: expand and clarify README

[jscarle]

Summary

• rewrite the README with a clearer structure, adding a table of contents and reorganized guidance
• expand descriptions of handler styles, configuration options, and request/response metadata with new examples
• add practical tips and feature patterns to make the generator easier to adopt

Testing

• not run (documentation-only change)

---

Codex Task