docs: note session storage is effectively mandatory (FLOOD_WAIT)

Without a persisted session every Run re-authorizes the bot and Telegram
rate-limits repeated logins with a growing FLOOD_WAIT. Document this on
Options.Storage, the package doc and CLAUDE.md.

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

Author: ernado

CLAUDE.md

@@ -88,7 +88,9 @@ can't back the `peers.Peer` that chat-management methods need.
   front end.
 - `storage/` — `BBoltStorage`, one bbolt file holding session + peer cache + update state. The
   composite `Storage` interface (in `options.go`) requires all of those; `Options.Storage` is
-  optional and everything stays in memory when nil.
+  optional and everything stays in memory when nil — but is effectively mandatory in production:
+  without a persisted session every `Run` re-authorizes the bot and Telegram answers repeated
+  logins with a growing `FLOOD_WAIT`.
 - `internal/botdoc/` + `cmd/botdoc/` — fetch/extract the published Bot API docs. Kept as a reference
   oracle and as a conformance check (`conformance_test.go`) that catches *unacknowledged* drift
   between the hand-written surface and the published API.

doc.go

@@ -49,6 +49,16 @@
 // helpers Code, AsFloodWait and AsChatMigrated. Context cancellation passes
 // through unchanged so callers can errors.Is on ctx.Err().
 //
+// # Persistence
+//
+// With no Options.Storage everything is kept in memory and nothing survives a
+// restart. Providing a Storage (storage.BBoltStorage satisfies it) is strongly
+// recommended for any long-lived bot: without a persisted session every Run
+// re-authorizes the bot, and Telegram rate-limits repeated logins with
+// FLOOD_WAIT — which grows with each retry and can lock the bot out on restart
+// loops. Persisting the session lets the bot reuse its authorization instead of
+// logging in again.
+//
 // # Sealed unions
 //
 // Where the Bot API uses "one of" objects (ChatID, InputFile, ReplyMarkup,

options.go

@@ -38,8 +38,15 @@ type Options struct {
 	// Device describes the client to Telegram. Optional.
 	Device telegram.DeviceConfig
 
-	// Storage persists session, peers and update state. Optional; in-memory if
-	// nil (nothing survives a restart).
+	// Storage persists session, peers and update state. In-memory if nil, in
+	// which case nothing survives a restart.
+	//
+	// Providing a Storage is strongly recommended for any long-lived bot:
+	// without a persisted session every Run starts a fresh one and re-authorizes
+	// the bot, and Telegram rate-limits repeated logins with FLOOD_WAIT, which
+	// grows with each retry and can lock the bot out on restart loops. With a
+	// persisted session the bot reuses its authorization instead of logging in
+	// again.
 	Storage Storage
 
 	// OnStart is called once, after the bot is authorized and update gap