(new): support Bot API 10.3

(fix): finalize v2 contracts
(tests): cover v2 migration
(doc): prepare release guidance

README.md

@@ -2,7 +2,7 @@
 
 ![Laniakea](assets/logo.jpg)
 
-[![Go Version](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go&style=flat-square)](https://go.dev/)
+[![Go Version](https://img.shields.io/badge/Go-1.27+-00ADD8?logo=go&style=flat-square)](https://go.dev/)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg?style=flat-square)](LICENSE)
 ![Gitea Release](https://img.shields.io/gitea/v/release/ScuroNeko/Laniakea?gitea_url=https%3A%2F%2Fgit.scuroneko.dev&sort=semver&display_name=release&style=flat-square&color=purple&link=https%3A%2F%2Fgit.scuroneko.dev%2FScuroNeko%2FLaniakea%2Freleases)
 
@@ -30,13 +30,7 @@ A lightweight, easy-to-use, and performant Telegram Bot API wrapper for Go. It s
 ## 📦 Installation
 
 ```bash
-go get git.scuroneko.dev/scuroneko/laniakea
-```
-
-or
-
-```bash
-go get github.com/scuroneko/laniakea
+go get git.scuroneko.dev/scuroneko/laniakea/v2@v2.0.0-rc.1
 ```
 
 ## 🚀 Quick Start (with step-by-step explanation)
@@ -48,7 +42,7 @@ package main
 import (
 	"log"
 
-	"git.scuroneko.dev/scuroneko/laniakea" // Import the Laniakea library
+	"git.scuroneko.dev/scuroneko/laniakea/v2" // Import the Laniakea library
 )
 
 // echo is a command handler function.
@@ -288,32 +282,32 @@ import (
 
 // One-shot runner — fires once in a goroutine when the bot starts (default).
 bot.AddRunner(
-    laniakea.NewRunner("seed-cache", func(b *laniakea.Bot[*MyDB]) error {
-        return b.GetAppData().SeedCache()
-    }),
+	laniakea.NewRunner("seed-cache", func(ctx context.Context, b *laniakea.Bot[*MyDB]) error {
+		return b.GetAppData().SeedCache(ctx)
+	}),
 )
 
 // Periodic runner — fires every 10 minutes in a goroutine.
 bot.AddRunner(
-    laniakea.NewContextRunner("refresh-stats", func(ctx context.Context, b *laniakea.Bot[*MyDB]) error {
-        return b.GetAppData().RefreshStats(ctx)
-    }).Every(10 * time.Minute),
+	laniakea.NewRunner("refresh-stats", func(ctx context.Context, b *laniakea.Bot[*MyDB]) error {
+		return b.GetAppData().RefreshStats(ctx)
+	}).Every(10 * time.Minute),
 )
 
 // Synchronous one-shot — blocks runtime startup until it completes.
 bot.AddRunner(
-    laniakea.NewRunner("migrate", func(b *laniakea.Bot[*MyDB]) error {
-        return b.GetAppData().Migrate()
-    }).Async(false),
+	laniakea.NewRunner("migrate", func(ctx context.Context, b *laniakea.Bot[*MyDB]) error {
+		return b.GetAppData().Migrate(ctx)
+	}).Async(false),
 )
 ```
 
 Builder methods:
-- `Async(bool) *Runner[T]` — if `true` (default), runs in a goroutine; if `false`, blocks runtime startup.
-- `Every(time.Duration) *Runner[T]` — sets the repeat interval. Zero (default) means run once; positive value repeats. Periodic runners require `Async(true)`.
+- `Async(bool) Runner[T]` — if `true` (default), runs in a goroutine; if `false`, blocks runtime startup.
+- `Every(time.Duration) Runner[T]` — sets the repeat interval. Zero (default) means run once; positive value repeats. Periodic runners require `Async(true)`.
 
-Prefer `NewContextRunner` for I/O and blocking work. Its context is canceled
-when polling or webhook execution stops, allowing shutdown to complete.
+Every runner receives a context that is canceled when polling or webhook
+execution stops. I/O and blocking work should pass it to downstream calls.
 
 ## 🧩 Middleware
 Middleware are functions that run before a command handler. They are perfect for cross-cutting concerns like logging, access control, rate limiting, or modifying the context.
@@ -364,7 +358,7 @@ func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
 
 ## ⚙️ Advanced Configuration
 - **Inline Keyboards**: Build keyboards using `laniakea.NewInlineKeyboardJSON`, `laniakea.NewInlineKeyboardBase64`, or `laniakea.NewInlineKeyboard`. `Bot.SetPayloadType(...)` defines the default payload format, and `InlineKeyboard.SetPayloadType(...)` overrides it for one keyboard.
-- **Keyboard Validation**: Call `InlineKeyboard.GetValidated()` before sending untrusted or dynamically generated callback payloads; Telegram limits `callback_data` to 1–64 bytes.
+- **Keyboard Validation**: `InlineKeyboard.Get()` validates every button and row before returning markup; Telegram limits `callback_data` to 1–64 bytes. Use `SetUnlimitedRows()` when automatic wrapping must be disabled explicitly.
 - **Rate Limiting**: Pass a configured utils.RateLimiter via BotOpts to handle Telegram's rate limits gracefully.
 - **Observers**: Runtime observer callbacks are dispatched asynchronously in order through a bounded queue. Slow observers do not block handlers; overload drops events with sampled warnings, and shutdown drains queued events.
 - **Localization**: `L10n` is safe for concurrent use once attached to the bot.
@@ -382,7 +376,7 @@ func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
 This project is licensed under the GNU General Public License v3.0 — see the [LICENSE](LICENSE) file for details.
 
 ## 📚 Learn More
-[GoDoc](https://pkg.go.dev/git.scuroneko.dev/scuroneko/laniakea)
+[GoDoc](https://pkg.go.dev/git.scuroneko.dev/scuroneko/laniakea/v2)
 
 [Wiki](https://git.scuroneko.dev/ScuroNeko/Laniakea/wiki)