docs: auto-generate markdown reference + soften README

- Add gomarkdoc-driven reference docs in docs/reference/, regenerated
  automatically by 'make regen' alongside the api/ codegen
- New 'make docs' target installs gomarkdoc on first run; 'make
  docs-check' is a CI gate
- Fold doc-clean assertion into existing codegen-clean job (single
  diff check covers spec + api + reference)
- Rewrite README header: logo via <picture>, friendlier tagline,
  emoji-led 'Why you'll like it' bullets instead of Why-table
- Drop duplicate echo snippet, soften 'Codegen pipeline' section into
  'Keeping up with Telegram'
- Link reference from README, Pages nav, and a new Markdown reference
  card on index.html (target = GitHub source view, renders .md natively)

docs/reference/README.md

@@ -0,0 +1,25 @@
+# API Reference
+
+Auto-generated from Go source comments by [gomarkdoc](https://github.com/princjef/gomarkdoc). Do not edit by hand — run `make docs` to regenerate.
+
+## Packages
+
+| Package | Description |
+|---|---|
+| [`api`](api.md) | Telegram Bot API types and method wrappers — 176 methods, 301 types, fully generated |
+| [`client`](client.md) | Bot client, codec, HTTP doer, retry middleware |
+| [`transport`](transport.md) | Long-poll and webhook transports |
+| [`dispatch`](dispatch.md) | Update router, filters, handler groups, named handlers |
+| [`dispatch/conversation`](dispatch/conversation.md) | Multi-step conversation state machines |
+| [`dispatch/filters/message`](dispatch/filters/message.md) | Message filters — `Command`, `Text`, `IsReply`, etc. |
+| [`dispatch/filters/callback`](dispatch/filters/callback.md) | Callback query filters |
+| [`dispatch/filters/inline`](dispatch/filters/inline.md) | Inline query filters |
+| [`dispatch/filters/chatmember`](dispatch/filters/chatmember.md) | Chat member update filters |
+| [`dispatch/filters/chatjoinrequest`](dispatch/filters/chatjoinrequest.md) | Join request filters |
+| [`dispatch/filters/precheckoutquery`](dispatch/filters/precheckoutquery.md) | Pre-checkout filters for payments |
+
+## Also see
+
+- [Project home](../index.html) — landing page with examples and overview
+- [GitHub repository](https://github.com/lukaszraczylo/go-telegram)
+- [pkg.go.dev](https://pkg.go.dev/github.com/lukaszraczylo/go-telegram) — official Go package documentation