docs(17-01): complete Telegram Bot package foundation plan

- Summary: telego bot skeleton with auth, rate limiting, 10 command stubs
- Updated STATE.md, ROADMAP.md, REQUIREMENTS.md

.planning/phases/17-telegram-scheduler/17-01-SUMMARY.md

@@ -0,0 +1,88 @@
+---
+phase: 17-telegram-scheduler
+plan: "01"
+subsystem: telegram-bot
+tags: [telegram, bot, telego, long-polling, auth]
+dependency_graph:
+  requires: []
+  provides: [pkg/bot/bot.go, pkg/bot/bot_test.go]
+  affects: [cmd/stubs.go]
+tech_stack:
+  added: [github.com/mymmrac/telego@v1.8.0]
+  patterns: [long-polling, chat-id-authorization, per-user-rate-limiting]
+key_files:
+  created: [pkg/bot/bot.go, pkg/bot/bot_test.go]
+  modified: [go.mod, go.sum]
+decisions:
+  - "telego v1.8.0 promoted from indirect to direct dependency"
+  - "Context cancellation for graceful shutdown rather than explicit StopLongPolling call"
+  - "Rate limit cooldown: 60s for scan/verify/recon, 5s for other commands"
+metrics:
+  duration: 3min
+  completed: "2026-04-06T14:28:15Z"
+  tasks_completed: 2
+  tasks_total: 2
+  files_changed: 4
+---
+
+# Phase 17 Plan 01: Telegram Bot Package Foundation Summary
+
+Telego v1.8.0 bot skeleton with long-polling lifecycle, chat-ID allowlist auth, per-user rate limiting, and 10 command handler stubs.
+
+## What Was Built
+
+### pkg/bot/bot.go
+- `Config` struct with Token, AllowedChats, DB, ScanEngine, ReconEngine, ProviderRegistry, EncKey fields
+- `Bot` struct wrapping telego.Bot with cancel func and rate limit state
+- `New(cfg Config) (*Bot, error)` creates telego bot from token
+- `Start(ctx context.Context) error` registers commands via SetMyCommands, starts long polling, dispatches updates
+- `Stop()` cancels context to trigger graceful shutdown
+- `isAllowed(chatID)` checks chat against allowlist (empty = allow all)
+- `checkRateLimit(userID, cooldown)` enforces per-user command cooldowns
+- `dispatch()` routes incoming messages to handlers with auth + rate limit checks
+- `reply()` and `replyPlain()` helpers for MarkdownV2 and plain text responses
+- Handler stubs for all 10 commands: scan, verify, recon, status, stats, providers, help, key, subscribe, unsubscribe
+
+### pkg/bot/bot_test.go
+- TestNew_EmptyToken: verifies error on empty token
+- TestIsAllowed_EmptyList: verifies open access with no restrictions
+- TestIsAllowed_RestrictedList: verifies allowlist filtering
+- TestCheckRateLimit: verifies cooldown enforcement and per-user isolation
+
+## Commits
+
+| # | Hash | Message |
+|---|------|---------|
+| 1 | 0d00215 | feat(17-01): add telego dependency and create Bot package skeleton |
+| 2 | 2d51d31 | test(17-01): add unit tests for Bot creation and auth filtering |
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Known Stubs
+
+| File | Function | Purpose | Resolved By |
+|------|----------|---------|-------------|
+| pkg/bot/bot.go | handleScan | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleVerify | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleRecon | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleStatus | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleStats | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleProviders | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleHelp | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleKey | Stub returning "Not yet implemented" | Plan 17-03 |
+| pkg/bot/bot.go | handleSubscribe | Stub returning "Not yet implemented" | Plan 17-04 |
+| pkg/bot/bot.go | handleUnsubscribe | Stub returning "Not yet implemented" | Plan 17-04 |
+
+These stubs are intentional -- the plan's goal is the package foundation, not handler implementation.
+
+## Self-Check: PASSED
+
+- pkg/bot/bot.go: FOUND
+- pkg/bot/bot_test.go: FOUND
+- Commit 0d00215: FOUND
+- Commit 2d51d31: FOUND
+- go build ./pkg/bot/...: OK
+- go test ./pkg/bot/...: 4/4 PASS
+- telego v1.8.0 in go.mod: FOUND (direct)