docs(17-03): complete bot command handlers plan

- SUMMARY.md with implementation details and self-check passed
- STATE.md updated with progress, metrics, decisions
- Requirements TELE-01, TELE-02, TELE-03, TELE-04, TELE-06 marked complete

.planning/REQUIREMENTS.md

@@ -232,12 +232,12 @@ Requirements for initial release. Each maps to roadmap phases.
 
 ### Telegram Bot
 
-- [ ] **TELE-01**: /scan command — remote scan trigger
+- [x] **TELE-01**: /scan command — remote scan trigger
-- [ ] **TELE-02**: /verify command — key verification
+- [x] **TELE-02**: /verify command — key verification
-- [ ] **TELE-03**: /recon command — dork execution
+- [x] **TELE-03**: /recon command — dork execution
-- [ ] **TELE-04**: /status, /stats, /providers, /help commands
+- [x] **TELE-04**: /status, /stats, /providers, /help commands
 - [ ] **TELE-05**: /subscribe and /unsubscribe for auto-notifications
-- [ ] **TELE-06**: /key <id> command — full key detail in private chat
+- [x] **TELE-06**: /key <id> command — full key detail in private chat
 - [ ] **TELE-07**: Auto-notification on new key findings
 
 ### Scheduled Scanning

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: Completed 16-01-PLAN.md
+stopped_at: Completed 17-03-PLAN.md
-last_updated: "2026-04-06T13:48:35.313Z"
+last_updated: "2026-04-06T14:36:30.928Z"
 last_activity: 2026-04-06
 progress:
   total_phases: 18
-  completed_phases: 14
+  completed_phases: 15
-  total_plans: 85
+  total_plans: 86
-  completed_plans: 83
+  completed_plans: 84
   percent: 20
 ---
 
@@ -100,6 +100,7 @@ Progress: [██░░░░░░░░] 20%
 | Phase 15 P01 | 3min | 2 tasks | 13 files |
 | Phase 15 P03 | 4min | 2 tasks | 11 files |
 | Phase 16 P01 | 4min | 2 tasks | 6 files |
+| Phase 17 P03 | 5min | 3 tasks | 6 files |
 
 ## Accumulated Context
 
@@ -152,6 +153,8 @@ Recent decisions affecting current work:
 - [Phase 16]: VT uses x-apikey header per official API v3 spec
 - [Phase 16]: IX uses three-step flow: POST search, GET results, GET file content
 - [Phase 16]: URLhaus tag lookup with payload endpoint fallback
+- [Phase 17]: Telego v1.8.0 handler context pattern: *th.Context implements context.Context for scan/recon timeout propagation
+- [Phase 17]: /key enforced private-chat-only via chat.Type check; all other bot commands use masked keys
 
 ### Pending Todos
 
@@ -166,6 +169,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-06T13:46:09.383Z
+Last session: 2026-04-06T14:36:30.924Z
-Stopped at: Completed 16-01-PLAN.md
+Stopped at: Completed 17-03-PLAN.md
 Resume file: None

.planning/phases/17-telegram-scheduler/17-03-PLAN.md

@@ -0,0 +1,82 @@
+---
+phase: "17"
+plan: "03"
+type: implementation
+autonomous: true
+wave: 1
+depends_on: []
+requirements: [TELE-01, TELE-02, TELE-03, TELE-04, TELE-06]
+---
+
+# Phase 17 Plan 03: Bot Command Handlers
+
+## Objective
+
+Implement Telegram bot command handlers for /scan, /verify, /recon, /status, /stats, /providers, /help, and /key commands. The bot package wraps existing CLI functionality (scan engine, verifier, recon engine, storage queries, provider registry) and exposes it through Telegram message handlers using the telego library.
+
+## Context
+
+- @pkg/engine/engine.go — scan engine with Scan() method
+- @pkg/verify/verifier.go — HTTPVerifier with Verify/VerifyAll
+- @pkg/recon/engine.go — recon Engine with SweepAll
+- @pkg/storage/queries.go — DB queries (ListFindingsFiltered, GetFinding)
+- @cmd/scan.go — CLI scan flow (source selection, verification, persistence)
+- @cmd/recon.go — CLI recon flow (buildReconEngine, SweepAll, persist)
+- @cmd/keys.go — CLI keys management (list, show, verify)
+- @cmd/providers.go — Provider listing and stats
+
+## Tasks
+
+### Task 1: Add telego dependency and create bot package with handler registry
+type="auto"
+
+Create `pkg/bot/` package with:
+- `bot.go`: Bot struct wrapping telego.Bot, holding references to engine, verifier, recon engine, storage, providers registry, and encryption key
+- `handlers.go`: Handler registration mapping commands to handler functions
+- Add `github.com/mymmrac/telego` dependency
+
+Done when: `pkg/bot/bot.go` compiles, Bot struct has all required dependencies injected
+
+### Task 2: Implement all eight command handlers
+type="auto"
+
+Implement handlers in `pkg/bot/handlers.go`:
+- `/help` — list available commands with descriptions
+- `/scan <path>` — trigger scan on path, return findings (masked only, never unmasked in Telegram)
+- `/verify <id>` — verify a finding by ID, return status
+- `/recon [--sources=x,y]` — run recon sweep, return summary
+- `/status` — show bot status (uptime, last scan time, DB stats)
+- `/stats` — show provider/finding statistics
+- `/providers` — list loaded providers
+- `/key <id>` — show full key detail (private chat only, with unmasked key)
+
+Security: /key must only work in private chats, never in groups. All other commands use masked keys only.
+
+Done when: All eight handlers compile and handle errors gracefully
+
+### Task 3: Unit tests for command handlers
+type="auto"
+
+Write tests in `pkg/bot/handlers_test.go` verifying:
+- /help returns all command descriptions
+- /scan with missing path returns usage error
+- /key refuses to work in group chats
+- /providers returns provider count
+- /stats returns stats summary
+
+Done when: `go test ./pkg/bot/...` passes
+
+## Verification
+
+```bash
+go build ./...
+go test ./pkg/bot/... -v
+```
+
+## Success Criteria
+
+- All eight command handlers implemented in pkg/bot/handlers.go
+- Bot struct accepts all required dependencies via constructor
+- /key command enforced private-chat-only
+- All commands use masked keys except /key in private chat
+- Tests pass

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

@@ -0,0 +1,68 @@
+---
+phase: "17"
+plan: "03"
+subsystem: telegram-bot
+tags: [telegram, bot, commands, telego]
+dependency_graph:
+  requires: [engine, verifier, recon-engine, storage, providers]
+  provides: [bot-command-handlers]
+  affects: [serve-command]
+tech_stack:
+  added: [github.com/mymmrac/telego@v1.8.0]
+  patterns: [telegohandler-command-predicates, context-based-handlers]
+key_files:
+  created: [pkg/bot/bot.go, pkg/bot/handlers.go, pkg/bot/source.go, pkg/bot/handlers_test.go]
+  modified: [go.mod, go.sum]
+decisions:
+  - "Handler signature uses telego Context (implements context.Context) for cancellation propagation"
+  - "/key command enforced private-chat-only via chat.Type check; all other commands use masked keys only"
+  - "Bot wraps existing engine/verifier/recon/storage/registry via Deps struct injection"
+metrics:
+  duration: 5min
+  completed: "2026-04-06"
+---
+
+# Phase 17 Plan 03: Bot Command Handlers Summary
+
+Telegram bot command handlers for 8 commands using telego v1.8.0, wrapping existing scan/verify/recon/storage functionality.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1+2 | Bot package + 8 command handlers | 9ad5853 | pkg/bot/bot.go, pkg/bot/handlers.go, pkg/bot/source.go, go.mod, go.sum |
+| 3 | Unit tests for handlers | 202473a | pkg/bot/handlers_test.go |
+
+## Implementation Details
+
+### Bot Package Structure
+
+- `bot.go`: Bot struct with Deps injection (engine, verifier, recon, storage, registry, encKey), RegisterHandlers method wiring telego BotHandler
+- `handlers.go`: 8 command handlers (/help, /scan, /verify, /recon, /status, /stats, /providers, /key) plus extractArg and storageToEngine helpers
+- `source.go`: selectBotSource for file/directory path resolution (subset of CLI source selection)
+
+### Command Security Model
+
+- `/key <id>`: Private chat only. Returns full unmasked key, refuses in group/supergroup chats
+- All other commands: Masked keys only. Never expose raw key material in group contexts
+- Scan results capped at 20 items with overflow indicator
+
+### Handler Registration
+
+Commands registered via `th.CommandEqual("name")` predicates on the BotHandler. Each handler returns `error` but uses reply messages for user-facing errors rather than returning errors to telego.
+
+## Decisions Made
+
+1. Handler context: telego's `*th.Context` implements `context.Context`, used for timeout propagation in scan/recon operations
+2. /key private-only: Enforced via `msg.Chat.Type == "private"` check, returns denial message in groups
+3. Deps struct pattern: All dependencies injected via `Deps` struct to `New()` constructor, avoiding global state
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Known Stubs
+
+None. All 8 handlers are fully wired to real engine/verifier/recon/storage functionality.
+
+## Self-Check: PASSED