docs(02): capture phase context

Phase 02: Telegram Integration
- Implementation decisions documented
- Phase boundary established

.planning/phases/02-telegram-integration/02-CONTEXT.md

@@ -0,0 +1,72 @@
+# Phase 2: Telegram Integration - Context
+
+**Gathered:** 2026-02-04
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Bidirectional messaging between Telegram and Claude Code with file support and status feedback. User sends messages/files in Telegram, Claude processes via persistent JSON-streamed subprocess, and responds with natural language summaries. Typing indicators and tool call notifications provide progress visibility.
+
+Lifecycle management (idle timeout, suspend/resume) is Phase 3. Output mode switching (verbose/smart) is Phase 4.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Conversation persistence
+- Use JSON streaming to Claude Code so conversations don't cold start for every message
+- Maintain persistent process per session rather than spawning fresh `claude -p` each turn
+- This is a key architectural shift from Phase 1's fresh-process-per-turn model
+
+### Response formatting
+- Use Telegram's native MarkdownV2 for formatting (bold, italic, code, links)
+- Claude should communicate in natural language about what it did — no raw code in responses
+- Telegram is a mobile-first, on-the-go interface — responses should be concise summaries of work done, not code dumps
+- Long responses split at smart boundaries (paragraph/code block breaks) — never break mid-code-block or mid-sentence
+
+### Progress feedback
+- Tool call notifications include tool name + target (e.g., "Reading config.json...", "Running npm test...")
+- No timeout as long as there is progress — Claude Code tasks can legitimately take a while
+
+### Claude's Discretion
+- Whether to show typing indicator only vs typing + status messages while working
+- Whether to send periodic progress updates on long tasks (2+ min) or just wait for completion
+- Whether tool call notifications edit a single message in-place or appear as separate messages
+- Whether multi-part responses come as one consolidated message or multiple messages
+- Error message verbosity and format
+
+### File handling
+- Photos: save to session folder AND auto-analyze (describe what's in the image immediately)
+- Documents/files: save directly to the session's working directory so Claude can reference them
+- Claude can send files back to user as Telegram attachments when appropriate (scripts, logs, configs)
+- Files sent without message text: infer intent from conversation context rather than asking
+
+### Error & edge cases
+- No active session + message: prompt user to create one ("No active session. Use /new <name> to start one")
+- Rapid sequential messages: batch into a single prompt before sending to Claude
+- No hard timeout — as long as progress is happening, let Claude work
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "Telegram is used from a phone when I'm on the move — Claude should focus on doing the work and notifying me how it was solved and what was solved, without showing me code — use natural language"
+- JSON streaming to avoid cold starts was explicitly called out as essential
+- Batching rapid messages avoids wasting turns on partial thoughts
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 02-telegram-integration*
+*Context gathered: 2026-02-04*