docs: add Telegram capacity & limits explanation (#405)

[Nathan Schram (nathanschram)]

Summary

Adds a user-facing capacity-and-limits explanation doc for Untether, prompted by a user question about how many concurrent agents one bot token can realistically handle. Covers Telegram Bot API limits, Untether's outbox pacing and concurrency model, where the system breaks first (RAM → Telegram 30/sec → FDs), and scaling patterns.

Companion issue: #405 (per-chat retry_at in TelegramOutbox honouring Bot API 7.8's parameters.scope field).

Changes

• New docs/explanation/telegram-capacity.md (~140 lines) — authoritative single-source explanation, Diátaxis "explanation" category
• README.md — one-line mention near Quick Start + entry in Help Guides → Reference
• docs/how-to/troubleshooting.md — new "Telegram rate limit / flood wait" section linking to the explanation
• docs/reference/transports/telegram.md — cross-link in "Rate limiting + backoff" section

Test plan

• python3 scripts/validate_release.py passes (docs-only, no version bump required)
• All telegram-capacity cross-references resolve (grep + relative path check)
• Anchor #telegram-rate-limit--flood-wait matches GitHub's slug for the new troubleshooting heading
• Render check on GitHub (tables, code fences, links) after PR opens

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7a1e28bb-6a66-4023-858f-4332db2b0b7c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/telegram-capacity-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}