docs: improve README onboarding and documentation generation

[cmilesio]

What

• Rework the README into a task-oriented package guide with clear entry points, package responsibilities, and common workflows.
• Cover graceful shutdown, middleware phases, handler testing, Prometheus ownership, OpenAPI generation, WebSockets, Echo escape hatches, and client-IP trust.
• Move annotated function and method examples into generated API.md, while directing users to pkg.go.dev for the complete exported API.
• Remove stale static test and package-coverage badges in favor of live CI and Codecov status.
• Repair example generation so multiline GoDoc examples remain intact, formatted, and deterministic, then regenerate the checked-in examples.
• Correct 200/204 examples and teach Pre for middleware that must affect route matching.

Why

The README had grown to 1,708 lines, with most of the useful onboarding buried beneath a generated reference that did not include important exported types and configuration fields. New users could see several ways to register routes, but not why they would choose one or how the packages fit together.

Some examples were also actively misleading: status-code output did not match the code, and path- or method-changing middleware was shown in the wrong routing phase. The standalone example generator could not reproduce current GoDoc without truncating programs, which allowed checked-in examples and their source comments to drift apart.

This gives users a shorter path from installation to a working application, makes operational boundaries explicit, and restores documentation generation as a reproducible source-of-truth workflow without changing the public API or minimum Go version.

[codecov-commenter]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️