telegram-dev 0.4.0__py3-none-any.whl

telegram_dev_skill/references/business-and-commerce.md

@@ -0,0 +1,39 @@
+# Business, commerce, gifts and stories
+
+Read the relevant section only. Identify the acting bot/user/business account, destination, payer/recipient and requested monetary or visibility outcome. Verify current numeric limits, rights and eligibility immediately before implementation.
+
+## Business connections
+
+Resolve the active connection and its granted rights. Separate the connection identifier, business owner and managed conversation; do not use the owner's private chat as a substitute destination. Thread the required business context through supported method calls and incoming message/edit/deletion handlers. Handle disablement and changed rights without silently reverting to ordinary bot messages.
+
+Check each requested action independently: messaging/read/delete, profile edits, gift/Stars access and stories use distinct permissions. A connected bot is not an unrestricted user-account session; a business account feature described in raw MTProto may not be exposed by the same Bot API method. For auto replies, inspect documented eligibility windows and managed recipients instead of hardcoding a remembered rule.
+
+Sources: [business account features](https://core.telegram.org/api/business), [connected business bots](https://core.telegram.org/api/bots/connected-business-bots), [connection object](https://core.telegram.org/bots/api#businessconnection), [rights object](https://core.telegram.org/bots/api#businessbotrights).
+
+## Payments for goods and services
+
+Classify digital versus physical goods/services before choosing a payment mechanism. The current digital-goods flow inside Telegram uses Stars (`XTR`); physical goods/services have a separate provider flow. Verify the current requirements for the actual product and delivery surface instead of copying invoice parameters between them.
+
+Model invoice creation, checkout validation and payment completion as distinct states. A pre-checkout approval or client popup result does not establish a completed paid order. Deliver from the authoritative successful-payment event, validate order/amount/currency/payer against server-side state, and deduplicate fulfillment. Retain the Telegram charge identity needed for reconciliation/refunds, separate from a provider's identifier. Handle a delayed or repeated event and avoid accepting another payment for a single-use order unless the product permits it. Use the documented checkout deadline, test environment and current customer-support/refund requirements.
+
+Sources: [digital goods](https://core.telegram.org/bots/payments-stars), [physical goods](https://core.telegram.org/bots/payments), [payment types and methods](https://core.telegram.org/bots/api#payments).
+
+## Other Stars and monetization flows
+
+An invoice payment, subscription, paid-media unlock, paid message, suggested-post settlement and business-to-bot transfer are different transactions. Select the matching flow; do not implement all as `sendInvoice`. For subscriptions, distinguish recurring bot services from channel membership and model expiry, cancellation and renewal. For paid media, verify allowed content and recipient/creator support. For suggested posts, inspect proposal, acceptance, publication and settlement/refund lifecycle. Represent amounts using the precision specified by each API, including fractional units where exposed; display balances and transaction direction correctly.
+
+Sources: [Stars](https://core.telegram.org/api/stars), [subscriptions](https://core.telegram.org/api/subscriptions), [paid media](https://core.telegram.org/api/paid-media), [suggested posts](https://core.telegram.org/api/suggested-posts). Discover paid messages, revenue, affiliate programs and giveaways from [the live index](https://core.telegram.org/api).
+
+## Gifts and collectibles
+
+Resolve whether the user wants to purchase/send a catalog gift, manage an already-owned gift, convert it, upgrade it into a collectible, transfer it, display it, resell it or participate in an auction. These require different identifiers and entitlement/balance checks. Read the exact object and operation; a catalog `gift_id` is not interchangeable with an owned/unique gift identifier. Separate regular gifts, collectible gifts, Premium gifts and giveaway prizes. Confirm the authorized account and recipient before irreversible spending or ownership changes. After an ambiguous timeout, reconcile ownership or transaction history before retrying.
+
+Sources: [gifts and their lifecycle](https://core.telegram.org/api/gifts), [Bot API gift/business methods](https://core.telegram.org/bots/api), current gift-auction article linked by [the API index](https://core.telegram.org/api).
+
+## Stories
+
+Determine whether a user, channel or managed business account publishes the story, and select the matching API. The Bot API has business-story operations; do not claim stories always require a user session. Check current rights, eligibility, media type, active period, archive/profile behavior, caption entities, areas and privacy. A normal chat video upload does not create a story. Editing/reposting/deleting may have narrower ownership rules than viewing or posting.
+
+Sources: [Telegram stories](https://core.telegram.org/api/stories), [Bot API postStory](https://core.telegram.org/bots/api#poststory), [business rights](https://core.telegram.org/bots/api#businessbotrights).
+
+Useful acceptance checks include duplicate-payment fulfillment, revoked business rights, correct owned-gift identity, actual story response and expected privacy/destination. Mocked calls establish request construction only; state when no live acceptance or settlement was verified.

telegram_dev_skill/references/buttons-and-custom-emoji.md

@@ -0,0 +1,51 @@
+# Colored buttons and premium/custom emoji
+
+These cases come from the user's reported failures. The examples below were checked against the official Bot API on 2026-10-10. Recheck the live specification when implementing; this date is not a release date.
+
+## “Сделай красную кнопку”
+
+Determine the actual surface from the project: reply keyboard, inline keyboard, Mini App content, or a native Mini App button. If the project already establishes it, do not ask the user again.
+
+Current Bot API `KeyboardButton` and `InlineKeyboardButton` document a `style` field with `danger` (red), `success` (green), and `primary` (blue). A red inline callback button can be represented as:
+
+```json
+{"text":"Отмена","style":"danger","callback_data":"cancel"}
+```
+
+This object belongs inside the existing inline keyboard structure. Preserve its required action: URL, callback, Mini App launch or other supported type. Do not add a second mutually exclusive action field.
+
+If the installed SDK rejects `style`, inspect its version and serialization behavior. An outdated constructor is a library compatibility problem. Choose a supported library upgrade or documented raw request path, and verify that `style` reaches Telegram. Do not silently omit the requested color, replace it with a red-circle emoji, or build a Mini App solely to work around an assumed restriction.
+
+The documented style is not a promise of identical pixels in every client/theme, nor arbitrary RGB support for bot keyboards. Mini App HTML/CSS and its native bridge buttons have their own APIs.
+
+Sources:
+- https://core.telegram.org/bots/api#keyboardbutton
+- https://core.telegram.org/bots/api#inlinekeyboardbutton
+- https://core.telegram.org/bots/webapps
+- https://core.telegram.org/bots/api-changelog
+
+## “Добавь premium emoji”
+
+Resolve where the custom emoji should appear. Text, button icon, reaction, status and sticker are different representations.
+
+- Message text: inspect `MessageEntity` with type `custom_emoji`, or the documented HTML `tg-emoji` markup. Use a real custom emoji identifier and a valid fallback emoji. With explicit entities, verify UTF-16 span offsets.
+- Keyboard icon: inspect `icon_custom_emoji_id` on the specific button type. Do not put HTML into a plain button label and expect it to render as an emoji entity.
+- Rich-message button: inspect `RichMessageButton` and its supported `RichText` representation separately; regular keyboard-label rules do not define rich-message markup.
+- Reaction, profile status or other use: inspect that surface's dedicated methods and eligibility rules; do not transfer text-message permissions automatically.
+
+At the verification date, Bot API documents custom emoji eligibility for bots that purchased additional usernames on Fragment, or for messages directly sent to private/group/supergroup chats when the bot owner has Telegram Premium. Read the current exact conditions for the actual field and destination. Do not reduce this to “bots cannot use Premium emoji”, “Premium always suffices”, or a guessed purchase requirement. Channels, inline results and other contexts must be checked separately.
+
+Do not invent identifiers or substitute a Unicode emoji/sticker without explaining that it changes the requested outcome. Obtain the identifier from authorized existing data or the relevant documented API. A numeric-looking value is not proof that it identifies a usable custom emoji.
+
+Sources:
+- https://core.telegram.org/bots/api#formatting-options
+- https://core.telegram.org/bots/api#messageentity
+- https://core.telegram.org/bots/api#inlinekeyboardbutton
+- https://core.telegram.org/bots/api#getcustomemojistickers
+- https://core.telegram.org/api/custom-emoji
+
+## Acceptance checks
+
+For the colored-button case: payload contains the correct style and action, the library preserves it, Telegram accepts it, and the target client shows the intended style when live verification is available.
+
+For emoji: correct surface/identifier, documented actor and destination eligibility, correct entities or icon field, and the requested result rather than a fallback substitution. Report offline-only verification as such.

telegram_dev_skill/references/client-development.md

@@ -0,0 +1,37 @@
+# Telegram client and protocol development
+
+Read this for account sessions, TDLib/MTProto, client-side state, calls, secret chats and export. A Telegram API account client, an MTProto-authorized bot and a Bot API service have different capabilities even when a library supports all three.
+
+## Choose the integration level
+
+Use the existing suitable library. TDLib manages networking, encryption and local state through its own API; inspect the installed build's generated schema and documentation rather than translating Bot API method names literally. Raw Telegram API clients use the application's credentials, authorization state and supported TL layer. MTProto is the protocol below that application API. Protocol implementation is appropriate only when the request actually requires it.
+
+Pin source/build revisions when investigating a client discrepancy. A method existing in the latest schema does not prove the project's TDLib build or target client supports it. For distribution of a third-party client, read the applicable [API terms](https://core.telegram.org/api/terms) and [client documentation](https://core.telegram.org/api), including required behavior relevant to that client.
+
+Sources: [TDLib](https://core.telegram.org/tdlib), [getting started](https://core.telegram.org/tdlib/getting-started), [TL schema](https://core.telegram.org/schema), [MTProto](https://core.telegram.org/mtproto), [official clients](https://telegram.org/apps).
+
+## Authorization and account state
+
+Follow the actual library's authorization state machine and current [user-authentication flow](https://core.telegram.org/api/auth). Codes, 2FA, QR login and [passkeys](https://core.telegram.org/api/passkeys) have different states and expiry semantics. Website OIDC/Mini App data does not authorize an MTProto account session. Do not expose credentials or session storage in generated logs; request account access only for the live account work actually authorized.
+
+Handle expiry, revocation, sign-out and account mismatch explicitly. Preserve the distinction between authenticating a user, registering an application and granting a bot a business connection. Use the dedicated [2FA](https://core.telegram.org/api/srp) or [QR-login](https://core.telegram.org/api/qr-login) source when that mode applies.
+
+## Peers, updates and synchronization
+
+Resolve the input peer using the chosen client's peer database and documented identifier/access-hash rules. A Bot API chat ID alone is not a complete raw `InputPeer`. Partial/min constructors may require contextual resolution; do not treat missing fields as a complete replacement for cached state.
+
+For a raw client, follow sequence-state, gap and difference rules for the relevant update stream. For TDLib, consume its update objects and persistence behavior instead of maintaining a second incompatible MTProto state machine. Check pagination semantics for each collection rather than assuming a common offset. On errors, handle DC migrations, revoked authentication, flood waits and expired file references using the documented recovery path; do not spin retries or duplicate non-idempotent actions.
+
+Sources: [updates](https://core.telegram.org/api/updates), [peer database](https://core.telegram.org/api/peers), [min constructors](https://core.telegram.org/api/min), [pagination](https://core.telegram.org/api/offsets), [errors](https://core.telegram.org/api/errors), [file references](https://core.telegram.org/api/file_reference).
+
+## Calls and secret chats
+
+Separate voice/video messages, one-to-one calls, group calls, live streaming and secret-chat messaging. Sending audio or joining a chat does not establish a media call. Read the current [call](https://core.telegram.org/api/calls) or [group-call](https://core.telegram.org/api/group-calls) flow, the chosen library's actual support, signaling, media transport/engine and permission/lifecycle requirements. Test with the intended participants and client platforms when authorized; a successful signaling call alone does not prove bidirectional audio/video.
+
+For [secret chats](https://core.telegram.org/api/end-to-end), use the documented E2E state/layer/sequence/rekey lifecycle and a suitable existing implementation. Do not call ordinary cloud-chat encryption “end to end”. Custom cryptographic work must follow [security guidelines](https://core.telegram.org/mtproto/security_guidelines) and the relevant linked protocol specifications, not invented schemes. State the client's actual secret-chat/call limitations rather than assuming a transport library implements them.
+
+## Other client features and export
+
+Account privacy, contacts/blocklist, folders/drafts, Saved Messages, scheduled messages, search, read state, reactions, themes, translation, transcription and notifications use distinct API families. Discover their current source from [the API index](https://core.telegram.org/api); inspect permissions and client configuration rather than hardcoding undocumented limits. For export, distinguish ordinary paginated history retrieval from [takeout](https://core.telegram.org/api/takeout), its lifecycle and data access. Preserve the requested account/scope and applicable content restrictions.
+
+Useful verification includes restart/update-gap recovery, partial peer objects, migrated chats, pagination without skips, actual auth-state transitions and the requested client-visible feature. Mocks and one library method returning successfully cannot establish full client interoperability.

telegram_dev_skill/references/feature-checks.md

@@ -0,0 +1,47 @@
+# Messaging, media and file implementation checks
+
+Read only the relevant section. For exact current fields/limits, open the linked official source and the selected method/type. Client appearance and upload acceptance are different verification levels.
+
+## Text and entities
+- Distinguish Bot API HTML/MarkdownV2 parsing from raw message entities and website HTML/CSS.
+- Compute offsets and lengths in UTF-16 code units where specified; do not use Python character counts or UTF-8 byte lengths as substitutes.
+- Test emoji before and inside the styled span, escaping, nesting, links, spoilers and code blocks that the actual request uses.
+- Check captions separately from message text and preserve their current restrictions.
+- Distinguish regular text/entities from the newer rich-message structures and their allowed markup. Inspect the live specification before deciding a table, structured block or embedded interaction requires a Mini App. Do not paste arbitrary browser HTML/CSS into an API that supports only a documented subset.
+
+Sources: [message entities](https://core.telegram.org/api/entities), [regular formatting](https://core.telegram.org/bots/api#formatting-options), [rich bot messages](https://core.telegram.org/bots/features#rich-messages).
+
+## Emoji and stickers
+- Distinguish Unicode emoji, custom emoji in text, emoji statuses, reactions, message effects, stickers and sticker sets.
+- Verify identifier types, current entitlement/actor restrictions and fallback rendering.
+- Inspect the actual asset dimensions, duration, frame rate, file size, encoding and transparency as applicable. Static, animated and video assets have different requirements.
+- “Animate this emoji” may request asset creation; “send this custom emoji” requires supported Telegram representation and identifiers. Resolve from context.
+- A sticker's semantic type (regular, mask, custom emoji) and its storage format (static, animated, video) are separate. Preserve the requested set type and editing operation; creating a local asset alone does not publish a usable Telegram set.
+
+Sources: [sticker asset requirements](https://core.telegram.org/stickers), [client sticker operations](https://core.telegram.org/api/stickers), [custom emoji](https://core.telegram.org/api/custom-emoji). Button-specific checks are in [buttons and custom emoji](buttons-and-custom-emoji.md).
+
+## Voice and video notes
+- For Bot API inspect `sendVoice`, `sendAudio`, `sendVideo`, `sendVideoNote` and their documented differences.
+- A круг/кружок normally means a video note: verify that the request and returned message use that type. Do not claim an ordinary square video has achieved it.
+- Probe and, when needed, convert local media; check actual codec/container, aspect ratio, duration and size against the selected method's current requirements.
+- Voice, audio and file attachments may display differently even when they share underlying audio data.
+- Upload success and client playback/rendering are distinct checks.
+
+Sources: [sendVoice](https://core.telegram.org/bots/api#sendvoice), [sendAudio](https://core.telegram.org/bots/api#sendaudio), [sendVideo](https://core.telegram.org/bots/api#sendvideo), [sendVideoNote](https://core.telegram.org/bots/api#sendvideonote).
+
+## File transfer and albums
+
+- Resolve whether the task needs a new upload, a reusable file identity, URL fetch, download, copy or forward. These have different behavior for captions, media type, attribution and protected content.
+- Bot API `file_id` and `file_unique_id` serve different purposes; verify the current reuse scope and restrictions. Do not pass an identity intended for comparison as a downloadable/sendable file reference.
+- Choose the documented cloud or local Bot API server behavior when upload/download limits matter. Do not claim a cloud-limit failure is a universal Telegram media limit, or deploy a new server without need.
+- For raw Telegram API transfers, inspect part size/alignment, DC/CDN behavior, integrity, resumption and actual file-reference expiry. Refresh the source message/reference through the documented path rather than endlessly retrying an expired reference.
+- Preserve album grouping and order, media compatibility, captions and expected per-message results. Sending several independent files is not proof of an album.
+- Preserve credentials while downloading: Bot API file URLs may contain the token; avoid placing them in public logs or product HTML. A downloaded filename/extension does not verify the bytes or codec.
+
+Sources: [Bot API file objects](https://core.telegram.org/bots/api#file), [local Bot API server](https://core.telegram.org/bots/api#using-a-local-bot-api-server), [MTProto files](https://core.telegram.org/api/files), [file references](https://core.telegram.org/api/file_reference).
+
+## Other message types
+
+For polls/quizzes, dice, locations/live locations, contacts, effects, reactions, checklists or paid media, inspect the matching message type and actor-specific method. Preserve its lifecycle: editing a live location, observing a vote, updating a checklist and buying locked media are not generic text sends. Check the exact update visibility and destination restrictions for the requested outcome.
+
+Sources: [current Bot API](https://core.telegram.org/bots/api), [Telegram API family index](https://core.telegram.org/api). For administration and conversation destinations use [groups and channels](groups-and-channels.md); commerce lifecycles use [business and commerce](business-and-commerce.md).

telegram_dev_skill/references/groups-and-channels.md

@@ -0,0 +1,35 @@
+# Groups, channels, moderation and conversation routing
+
+Read this for administrative actions, membership, forums, comments and channel direct messages. First resolve the actual chat type and acting identity from project state. A basic group, supergroup, broadcast channel, forum and channel direct-message conversation do not share every operation or event model.
+
+## Permissions and moderation
+
+Map the requested action to its exact required right, the bot/user's effective rights, the target member's role and the method's chat-type restrictions. An administrator label alone is insufficient. Restricting permissions, banning, unbanning, removing a member, deleting a message and preventing future joins have different outcomes; preserve the requested one. Evaluate defaults versus per-member overrides and expiry semantics using the selected API.
+
+For automatic moderation, use the event's actor fields rather than assuming `from` always identifies an ordinary user: channel posts, anonymous administrators and messages sent on behalf of chats need different handling. Build a targeted check from the user's actual moderation rule; do not infer authorization from a command appearing in a menu. Report missing rights before retrying. Destructive bulk changes should preserve the authorized selection and stopping condition.
+
+Sources: [chat types](https://core.telegram.org/api/channel), [rights](https://core.telegram.org/api/rights), [Bot API administrative methods](https://core.telegram.org/bots/api), [bot visibility](https://core.telegram.org/bots/faq#what-messages-will-my-bot-get).
+
+## Invites, joins and membership
+
+Distinguish a public username, invite link, join request and paid subscription invite. Verify who owns/manages the relevant link, approval rights, expiry, limits and update subscriptions. Revoking one link is not equivalent to disabling every route into a chat. Reconcile a membership change with live state when a delayed event would otherwise trigger an incorrect action.
+
+Sources: [invite links and join requests](https://core.telegram.org/api/invites), [subscription flows](https://core.telegram.org/api/subscriptions), [Bot API join-request objects](https://core.telegram.org/bots/api#chatjoinrequest).
+
+## Topics, comments and direct messages
+
+Forum topics can belong to a group or to a bot's enabled private-chat topic mode. Check the current mode and capabilities rather than assuming topics require a supergroup. Preserve the topic identity in sends and replies; choosing only the outer chat can send the answer into the wrong conversation. Topic create/edit/close/reopen/hide/delete operations have separate permission and lifecycle rules, including special handling for the General topic.
+
+Before enabling private bot topics, check the current [Bot Developer Terms](https://telegram.org/tos/bot-developers#6-2-6-enabling-topics-in-private-chats) for activation conditions and any effect on Stars purchases. Surface an actual documented cost when it changes the user's decision. Check each method's private-chat support independently rather than extending a supergroup-only operation to the new mode.
+
+A channel post, its discussion-group comment thread and a channel direct-message topic are separate destinations. Resolve the appropriate outer peer, root/thread/topic and reply target. Channel direct messages are not ordinary forum topics just because both expose a topic-like identifier. Test a reply when the original replied-to message is absent/deleted if routing fallback matters to the task.
+
+Sources: [forum and bot topics](https://core.telegram.org/api/forum), [discussion groups](https://core.telegram.org/api/discussion), [message threads](https://core.telegram.org/api/threads), [channel direct messages](https://core.telegram.org/api/monoforum).
+
+## Other community features
+
+For polls/quizzes, reactions, pins, checklists, scheduled posts, statistics, boosts, giveaways, antispam, protected content or channel monetization, follow the matching current API-index article and exact actor-specific method. Keep anonymous vote totals separate from identifiable votes; check which poll/reaction events the bot is entitled and subscribed to receive. A public post being readable does not imply every statistic or member is accessible. Protected media/content restrictions still apply to export or repost requests.
+
+Source: [feature-family index](https://core.telegram.org/api). Payment and suggested-post flows also use [business and commerce](business-and-commerce.md).
+
+Acceptance evidence should cover the intended destination and effective permission state: success in the requested topic, the target restriction/deletion result, or the relevant subscribed event. Avoid interpreting a successful API request as proof of every member's client view.

telegram_dev_skill/references/mini-apps-and-web.md

@@ -0,0 +1,40 @@
+# Mini Apps, web authentication and external integrations
+
+Read only the relevant surface. Website sign-in, Mini App launch authentication, a Telegram account session, login URL authorization, verification-code delivery and Passport are separate protocols. Determine the user's actual surface before choosing one.
+
+## Mini App lifecycle and bridge
+
+Identify the launch mechanism: keyboard, inline/menu button, main Mini App, direct link, inline mode or another documented entrypoint. Available data and send/return behavior depend on launch context. Inspect the supported bridge version and client capabilities before using newer methods. Keep the existing application and adapt the appropriate integration instead of producing only a browser mockup.
+
+Use current theme, viewport, keyboard, safe-area and fullscreen semantics relevant to the design. Handle events and cleanup across navigation rather than sizing the layout once from desktop browser dimensions. Request contact, location, write access or other capabilities through the documented user flow; unsupported/denied permissions need usable UI behavior. Test at least the actual client/platform implicated by the request.
+
+Source: [Mini App specifications and releases](https://core.telegram.org/bots/webapps).
+
+## Launch authentication
+
+Send raw `initData` to the backend and validate it with the official algorithm for the chosen trust model. Bot-token HMAC verification and third-party public-key signature verification have different data construction; do not mix them. The third-party mode does not require disclosure of the bot token. `initDataUnsafe`, decoded user fields and URL parameters are not independently authenticated.
+
+Bind validated data to the intended bot/environment and application session. Check authentication age with a justified expiry policy and protect authenticated mutations from replay/session confusion. Preserve the exact serialized fields through verification, then parse the verified data. Test tampering, stale payloads and production/test-environment mismatch using the actual backend path.
+
+Source: [validating Mini App data](https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app) and [third-party validation](https://core.telegram.org/bots/webapps#validating-data-for-third-party-use).
+
+## Website and native-mobile Telegram Login
+
+Read the current [Telegram Login](https://core.telegram.org/bots/telegram-login) documentation. It describes a Login library, native SDKs and OIDC Authorization Code Flow with PKCE. Do not build a new integration solely from a remembered legacy iframe/HMAC example. Conversely, preserve the project's existing legacy flow unless migration is requested or necessary; use [the archived widget](https://core.telegram.org/widgets/login-legacy) for its own verification specification.
+
+For OIDC, use the existing suitable authentication library with current discovery/endpoints, registered allowed URLs and server-side code exchange. Validate the ID token's signature, issuer, audience, lifetime and flow-bound nonce where used; protect redirect initiation with state and the chosen PKCE flow. Request only scopes required by the task and verify grants rather than inferring a phone number or permission to send messages from any successful sign-in. Avoid turning OIDC claims into a Telegram account/MTProto session.
+
+For [seamless URL authorization](https://core.telegram.org/api/url-authorization) or a Bot API login URL, implement its documented URL/domain and data checks. These are not Mini App `initData`.
+
+## Deep links and sharing
+
+Choose a link family matching the intent: bot start/startgroup, Mini App launch/startapp, invite/join, message/thread, username/profile, share, invoice or a client-specific `tg://` route. Follow [deep-link rules](https://core.telegram.org/api/links) and [bot start parameters](https://core.telegram.org/bots/features#deep-linking). Encode and validate parameters, preserve the destination and test the expected client/web fallback. A link itself does not authenticate its user or authorize a paid/actionable operation; use short-lived server-side state when linking identities.
+
+## Other integrations
+
+- [Gateway](https://core.telegram.org/gateway): verification-code delivery and verification/delivery-status lifecycle, not arbitrary bot announcements. Read current status, retry and request-identity semantics for the intended flow.
+- [Passport](https://core.telegram.org/passport): identity-document request/decryption/validation flow, not ordinary website login. Implement only the requested data types and handle relevant element errors.
+- [Web widgets](https://core.telegram.org/widgets): sharing/post embedding has its own behavior; embedding a post does not establish access to private chat data.
+- [Instant View](https://instantview.telegram.org/docs): article templates and rules, distinct from an app interface. Verify the actual article samples.
+
+Authentication acceptance means the backend rejects invalid data and establishes the correct app session. A rendered login button or successfully decoded JSON is insufficient.

telegram_dev_skill/references/surface-map.md

@@ -0,0 +1,54 @@
+# Official source and API map
+
+| Intent | Start here | Important distinction |
+|---|---|---|
+| Bot messages, commands, updates, keyboards, files, payments | https://core.telegram.org/bots/api and https://core.telegram.org/bots/features | HTTPS Bot API; inspect actor, chat and business connection restrictions per method. |
+| Embedded web interface | https://core.telegram.org/bots/webapps | JS bridge plus application backend and often Bot API. Check launch context, platform and supported version. |
+| User-account operations, custom clients, detailed platform features | https://core.telegram.org/api | Telegram API over MTProto; authorization type still governs permissions. |
+| Client implementation with local state/networking handled by a library | https://core.telegram.org/tdlib | TDLib's own types and methods differ from Bot API and raw TL schema. |
+| Protocol and transport | https://core.telegram.org/mtproto | Distinguish protocol mechanics from application API methods. |
+| Types, constructors, methods | https://core.telegram.org/schema | TL schema; follow links to related methods and constructors. |
+| Message formatting | https://core.telegram.org/api/entities and Bot API “Formatting options” | API-specific parsing, entities, UTF-16 offsets; website HTML is a different surface. |
+| Stickers and custom emoji | https://core.telegram.org/stickers ; https://core.telegram.org/api/stickers ; https://core.telegram.org/api/custom-emoji | Asset requirements, set operations, display permissions and message entities are separate concerns. |
+| Files, voice messages, video notes | https://core.telegram.org/bots/api ; https://core.telegram.org/api/files | Check intended message type, media preparation and chosen API together. |
+| Deep links | https://core.telegram.org/api/links | Link purpose and launch context matter. |
+| Verification-code delivery | https://core.telegram.org/gateway | Distinct service; not arbitrary bot messaging. |
+| Website/mobile sign-in | https://core.telegram.org/bots/telegram-login | Current Telegram Login library/native SDKs/OIDC; distinguish archived widget authentication. |
+| Legacy login widget and URL authorization | https://core.telegram.org/widgets/login-legacy and https://core.telegram.org/api/url-authorization | Existing widget and login URL flows use their own verification rules; do not apply Mini App authentication. |
+| Website sharing and post widgets | https://core.telegram.org/widgets | Embedding/sharing is distinct from authentication and Bot API messaging. |
+| Passport | https://core.telegram.org/passport | Separate identity-document integration. |
+| Instant View | https://instantview.telegram.org/docs | Article templates; not Mini Apps. |
+| Themes | https://core.telegram.org/api/themes | Client themes; distinct from Mini App theme parameters. |
+
+## Feature-family entrypoints
+
+The links below route to documentation rather than duplicate method catalogs. Some features have Bot API, TDLib and raw Telegram API variants with different permissions; inspect the selected method instead of transferring rules between them.
+
+| Family | Official sources | Read with |
+|---|---|---|
+| Business account features and connected bots | https://core.telegram.org/api/business ; https://core.telegram.org/api/bots/connected-business-bots | `business-and-commerce.md` |
+| Digital/physical payments and Stars | https://core.telegram.org/bots/payments-stars ; https://core.telegram.org/bots/payments ; https://core.telegram.org/api/stars | `business-and-commerce.md` |
+| Subscriptions, paid media, paid messages and suggested posts | https://core.telegram.org/api/subscriptions ; https://core.telegram.org/api/paid-media ; https://core.telegram.org/api/suggested-posts ; follow current index for paid messages | `business-and-commerce.md` |
+| Gifts, collectible upgrades/transfers/auctions, boosts and giveaways | https://core.telegram.org/api/gifts ; follow current index for auctions/boosts/giveaways | `business-and-commerce.md` |
+| Stories and story privacy/areas | https://core.telegram.org/api/stories ; current Bot API story methods | `business-and-commerce.md` |
+| Groups/channels, rights, topics and direct messages | https://core.telegram.org/api/channel ; https://core.telegram.org/api/rights ; https://core.telegram.org/api/forum ; https://core.telegram.org/api/monoforum | `groups-and-channels.md` |
+| Auth, 2FA, QR and passkeys | https://core.telegram.org/api/auth ; https://core.telegram.org/api/passkeys ; follow auth links for the chosen mechanism | `client-development.md` |
+| Client updates, peer state and errors | https://core.telegram.org/api/updates ; https://core.telegram.org/api/errors ; https://core.telegram.org/tdlib/getting-started | `client-development.md` |
+| One-to-one/group calls and secret chats | https://core.telegram.org/api/calls ; https://core.telegram.org/api/group-calls ; https://core.telegram.org/api/end-to-end ; https://core.telegram.org/mtproto/security_guidelines | `client-development.md` |
+| MTProto upload/download and expired references | https://core.telegram.org/api/files ; https://core.telegram.org/api/file_reference | `feature-checks.md` |
+
+For search, folders, drafts, Saved Messages, contacts, blocklist, privacy, scheduled messages, translation/transcription, polls/checklists, reactions/effects/statuses, themes/wallpapers, statistics, ads, verification, Premium/collectibles and takeout, start at https://core.telegram.org/api and select the matching article. Follow its schema links for exact types and availability. For evolving bot features such as managed bots, guest queries, bot-to-bot communication, AI assistants, rich messages, private topics and ephemeral responses, start with https://core.telegram.org/bots/features and the live Bot API. Never infer these are unsupported from a skill's static topic list.
+
+## Release sources
+
+- Bot API: https://core.telegram.org/bots/api-changelog and recent changes at https://core.telegram.org/bots/api
+- Mini Apps: release sections at https://core.telegram.org/bots/webapps
+- Telegram API layers: https://core.telegram.org/api/layers
+- TDLib: https://github.com/tdlib/td/blob/master/CHANGELOG.md
+- Product announcements and archive links: https://telegram.org/blog
+- Official product evolution timeline: https://telegram.org/evolution
+- Official client repository links: https://telegram.org/apps
+
+Keep API version, TL layer, TDLib version, client version, SDK version and publication date separate. Do not compare their numeric versions as one sequence. Record URL, section, applicable version/layer when stated, and retrieval date. An old changelog stays historical even when fetched today.
+
+The runtime indexes fetched public documentation and selected official repository files. Coverage depends on the installation's actual corpus status; the skill files alone are not a downloaded documentation mirror. The index does not mirror all client source repositories or reconstruct every past documentation revision. When client behavior requires source-code investigation, start from the official apps page, pin the repository revision, and mark the result as a code observation.