docs: expand package overview; remove third-party library references

Flesh out doc.go with construction, sending, receiving, errors and
sealed-union sections. Drop references to specific third-party libraries
across the docs and comments in favor of generic 'HTTP Bot API client'
wording.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

README.md

@@ -17,7 +17,7 @@ round trip, and keeps the raw `gotd/td` client one method call away
 
 ## Why MTProto instead of HTTP
 
-| | HTTP Bot API client (e.g. telego) | botapi |
+| | HTTP Bot API client | botapi |
 | --- | --- | --- |
 | Transport | HTTPS to `api.telegram.org` | MTProto via `gotd/td` |
 | Updates | `getUpdates` long-poll / webhook | persistent connection, no polling |

doc.go

@@ -2,9 +2,60 @@
 // github.com/gotd/td.
 //
 // Unlike HTTP Bot API clients, botapi does not talk to api.telegram.org. It
-// exposes the Bot API surface (types, methods, updates) but speaks MTProto
-// directly, which avoids Bot API server rate limits and gives access to the
-// raw client when needed (Bot.Raw).
+// exposes the familiar Bot API surface (types, methods, updates) but speaks
+// MTProto directly. That avoids the public Bot API server's rate limits, keeps
+// updates flowing over one persistent connection, and gives access to the raw
+// gotd client when the Bot API surface does not cover something (Bot.Raw).
 //
-// This package is under active reconstruction; see docs/roadmap.md.
+// # Construction
+//
+// New builds an unconnected bot from a BotFather token and an MTProto app
+// identity (AppID/AppHash from https://my.telegram.org — these are not the bot
+// token). Run connects, authorizes as a bot and serves updates until the
+// context is canceled:
+//
+//	bot, err := botapi.New(token, botapi.Options{AppID: id, AppHash: hash})
+//	if err != nil {
+//		return err
+//	}
+//	bot.OnCommand("start", func(c *botapi.Context) error {
+//		_, err := c.Reply("hello")
+//		return err
+//	})
+//	return bot.Run(ctx)
+//
+// # Sending
+//
+// Outgoing methods hang off *Bot, take a context first and a ChatID target, and
+// share functional SendOptions (ReplyTo, Silent, WithReplyMarkup,
+// WithParseMode, ...). A ChatID is constructed with ID (numeric) or Username:
+//
+//	bot.SendMessage(ctx, botapi.ID(chatID), "*hi*", botapi.WithParseMode(botapi.ParseModeMarkdownV2))
+//	bot.SendPhoto(ctx, botapi.Username("@channel"), botapi.FileURL("https://.../x.jpg"), "caption")
+//
+// # Receiving
+//
+// Updates are dispatched through a small handler framework. Register handlers
+// with the On* helpers (OnMessage, OnCommand, OnCallbackQuery, OnInlineQuery,
+// ...), narrow them with Predicates (Command, HasText, Regex, CallbackPrefix,
+// And/Or/Not, ...), and group shared middleware with Group/Use. Each handler
+// receives a *Context with helpers (Message, Sender, Reply, Send,
+// AnswerCallback, AnswerInline).
+//
+// # Errors
+//
+// Methods return errors shaped like the HTTP Bot API: an *Error with a Code and
+// Description (see errors_map.go). Extract it with errors.As, or use the
+// helpers Code, AsFloodWait and AsChatMigrated. Context cancellation passes
+// through unchanged so callers can errors.Is on ctx.Err().
+//
+// # Sealed unions
+//
+// Where the Bot API uses "one of" objects (ChatID, InputFile, ReplyMarkup,
+// InputMedia, ChatMember, InlineQueryResult, InputMessageContent, ...) this
+// package uses sealed interfaces: an interface with an unexported marker method
+// and a fixed set of concrete implementations, so an illegal state is
+// unrepresentable and switches over them are checked for exhaustiveness.
+//
+// See docs/roadmap.md for the implementation status.
 package botapi

docs/architecture.md

@@ -9,8 +9,8 @@
 
 A Go library that exposes the **Telegram Bot API** surface (types, methods,
 updates) but implements it **directly over MTProto** via `gotd/td` — not over
-HTTP to `api.telegram.org`. `telego` is the ergonomic bar to beat; the Bot API
-docs (<https://core.telegram.org/bots/api>) are the spec.
+HTTP to `api.telegram.org`. Existing HTTP Bot API clients set the ergonomic bar
+to beat; the Bot API docs (<https://core.telegram.org/bots/api>) are the spec.
 
 Design goals, in priority order (per project decision):
 
@@ -23,7 +23,7 @@ Design goals, in priority order (per project decision):
    errors (`FloodWait`, retry-after, network vs API vs not-implemented);
    proactive rate limiting.
 4. **A great handler framework** — composable middleware/router/predicates over
-   a native MTProto update stream, cleaner than `telegohandler`.
+   a native MTProto update stream.
 
 ## What changes from today's `botapi`
 
@@ -69,7 +69,7 @@ botapi/                      root package — the public library
      errors_map.go           tgerr -> botapi error codes
      engine.go               owns sender/peers/uploader/downloader/dispatcher
 
-  handler/                   the dispatcher framework (telegohandler rival)
+  handler/                   the dispatcher framework
      handler.go              Group, Use (middleware), predicates, routing
      predicates.go
      context.go
@@ -93,8 +93,9 @@ botapi/                      root package — the public library
 
 ### Type-safe unions
 
-`telego` models `ChatID` as a two-field struct (`{ID int64; Username string}`)
-and `InputFile` similarly — illegal states are representable. We use sealed
+A common HTTP-client approach models `ChatID` as a two-field struct
+(`{ID int64; Username string}`) and `InputFile` similarly — illegal states are
+representable. We use sealed
 interfaces (a private method makes them unforgeable from outside the package),
 with ergonomic constructors:
 
@@ -113,8 +114,7 @@ type InputFile interface{ isInputFile() }
 Discriminated incoming unions (`ChatMember`, `MessageOrigin`, `ReactionType`,
 `MenuButton`, `InputMedia`, inline-query results) are sealed interfaces with one
 concrete type per variant and a type switch — compile-time exhaustiveness via a
-linter, no `interface{}` + reflection, no runtime "try each type" unmarshal that
-`telego` does.
+linter, no `interface{}` + reflection, no runtime "try each type" unmarshal.
 
 ### Typed enums
 
@@ -170,10 +170,9 @@ grp.Use(Recover(), Timeout(30*time.Second))
 
 Predicates are `func(ctx, Update) bool`; middleware is
 `func(next Handler) Handler`. Context carries the `*Bot`, the update, and
-per-update values — designed in from the start (telego bolts a `Context` wrapper
-on after the fact and has the webhook `context.WithoutCancel` foot-gun, which we
-avoid because updates arrive over a persistent MTProto stream, not per-request
-HTTP).
+per-update values — designed in from the start, with no per-request HTTP
+`context.WithoutCancel` foot-gun because updates arrive over a persistent
+MTProto stream rather than per-request HTTP.
 
 ## Update flow (no long-poll, no webhook)
 

docs/building-blocks.md

@@ -1,9 +1,10 @@
 # gotd/td building blocks
 
 This document maps the high-level `github.com/gotd/td` primitives the Bot API
-library is built on. Unlike `telego`, this library does **not** talk HTTP to
-`api.telegram.org`. It implements the Bot API *surface* directly over MTProto
-using `gotd/td`. Everything below is a building block we wrap or translate.
+library is built on. Unlike HTTP Bot API clients, this library does **not** talk
+HTTP to `api.telegram.org`. It implements the Bot API *surface* directly over
+MTProto using `gotd/td`. Everything below is a building block we wrap or
+translate.
 
 All signatures verified against the local checkout at `/src/gotd/td`
 (`github.com/gotd/td`, module path confirmed). File:line references are to that
@@ -393,9 +394,9 @@ MTProto, peer resolution, gap recovery, or file transfer.
 
 ---
 
-## 11. What this buys us over telego
+## 11. What this buys us over HTTP Bot API clients
 
-| telego (HTTP Bot API) | this library (MTProto) |
+| HTTP Bot API client | this library (MTProto) |
 | --- | --- |
 | Subject to Bot API server rate limits | Direct MTProto; flood-wait only |
 | `file_id` opaque, must round-trip server | `fileid` codec is local; can construct locations |

docs/roadmap.md

@@ -1,7 +1,8 @@
 # Roadmap
 
 > Rebuild `github.com/gotd/botapi` from a codegen-first OpenAPI/ogen project into
-> a hand-written, MTProto-backed Bot API **library** that beats `telego`.
+> a hand-written, MTProto-backed Bot API **library** that beats existing HTTP
+> Bot API clients on ergonomics and performance.
 > Companion docs: `architecture.md`, `building-blocks.md`.
 
 Legend: ☐ todo · ◐ in progress · ☑ done
@@ -48,9 +49,8 @@ The hand-written Bot API surface. This is the bulk of the work. **Done** on
   the union discriminators
 - ☑ Sealed-interface unions: `ChatID`, `InputFile`, `ReplyMarkup`,
   `MessageOrigin`, `ChatMember`, `ReactionType`, `MenuButton`, `InputMedia`
-- ◐ Constructors / fluent setters (`ID`, `Username`, keyboard builders) — done;
-  the `telegoutil` equivalent. More fluent setters land alongside the methods
-  in Phase 3.
+- ◐ Constructors / fluent setters (`ID`, `Username`, keyboard builders) — done.
+  More fluent setters land alongside the methods in Phase 3.
 - ☑ Typed error hierarchy (`Error`, `AsFloodWait`, `ErrNotImplemented`)
 - ☑ Exhaustiveness lint config for unions (`gochecksumtype` + `exhaustive`;
   golangci config migrated to v2)
@@ -171,9 +171,9 @@ Deferred within Phase 5: payment answers
 - ☐ `pool.Pool` re-pointed at public `Bot`; GC, keepalive
 - ☐ `cmd/botapi` HTTP server as an optional example (local Bot-API server)
 - ☐ Examples: echo bot, media bot, inline bot, handler/middleware
-- ☐ Allocation tests on hot paths; benchmarks vs telego
+- ☐ Allocation tests on hot paths; benchmarks vs HTTP Bot API clients
 - ☐ Conformance test against kept `botdoc` extractor (API-version drift guard)
-- ☐ Docs: package docs, migration-from-telego guide, README
+- ☐ Docs: package docs, migration guide, README
 
 ## Phase 8 — Release
 

markup.go

@@ -77,7 +77,7 @@ func (*ReplyKeyboardMarkup) isReplyMarkup()  {}
 func (*ReplyKeyboardRemove) isReplyMarkup()  {}
 func (*ForceReply) isReplyMarkup()           {}
 
-// --- Constructors / builders (the type-safe telegoutil equivalent) ---
+// --- Constructors / builders (type-safe keyboard helpers) ---
 
 // InlineKeyboard builds an inline keyboard from rows of buttons.
 func InlineKeyboard(rows ...[]InlineKeyboardButton) *InlineKeyboardMarkup {