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)

.github/workflows/ci.yml

@@ -134,7 +134,7 @@ jobs:
       - name: Regenerate against pinned snapshot
         run: make regen-from-fixture
       - name: Assert clean diff
-        run: git diff --exit-code internal/spec/api.json api/
+        run: git diff --exit-code internal/spec/api.json api/ docs/reference/
 
   audit:
     runs-on: ubuntu-latest