From 1d64140575a5a56a06bbfde346630b628bb36841 Mon Sep 17 00:00:00 2001
From: Nexus Dev <nexus@local>
Date: Sat, 4 Apr 2026 02:53:46 +0000
Subject: [PATCH] docs(38): auto-generated context (discuss skipped)

---
 .../phases/38-telegram-bridge/38-CONTEXT.md   | 70 +++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 .planning/phases/38-telegram-bridge/38-CONTEXT.md

diff --git a/.planning/phases/38-telegram-bridge/38-CONTEXT.md b/.planning/phases/38-telegram-bridge/38-CONTEXT.md
new file mode 100644
index 00000000..c0f7ddf0
--- /dev/null
+++ b/.planning/phases/38-telegram-bridge/38-CONTEXT.md
@@ -0,0 +1,70 @@
+# Phase 38: Telegram Bridge - Context
+
+**Gathered:** 2026-04-04
+**Status:** Ready for planning
+**Mode:** Auto-generated (discuss skipped via workflow.skip_discuss)
+
+<domain>
+## Phase Boundary
+
+The user can message any Nexus agent from their phone via Telegram — text and voice notes both work, agent identity is visible on every reply, and the bot is set up through guided onboarding with no manual token entry in config files.
+
+Requirements: TGRAM-01, TGRAM-02, TGRAM-03, TGRAM-04, TGRAM-05, TGRAM-06, ONBRD-03
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Claude's Discretion
+All implementation choices are at Claude's discretion — discuss phase was skipped per user setting. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions.
+
+Key research findings to incorporate:
+- `grammy ^1.41.1` — TypeScript-native Telegram bot framework, long polling, clean file handling
+- Long polling via `bot.start()` — no public HTTPS required for Mac Mini behind NAT
+- Single bot for all agents — messages prefixed with `[AgentName]`
+- Telegram voice messages are OGG/Opus — download via `ctx.getFile()`, transcode to WAV 16kHz via ffmpeg before Whisper
+- TTS reply: synthesize via VoicePipelineService, convert WAV → OGG/Opus via ffmpeg, send via `ctx.replyWithVoice()`
+- Telegram token stored in nexus-settings.json (already in schema from Phase 36)
+- Bridge calls chatService and voicePipelineService directly (same-process, no HTTP round-trip)
+- Acknowledge updates immediately, process async to prevent Telegram resending
+- chatId → sessionId mapping: lightweight in-memory Map (single-user deployment)
+- Bridge service must be under 500 lines (TGRAM-06)
+- Onboarding BotFather setup: wizard step with guided token entry and validation
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `server/src/services/voice-pipeline.ts` — VoicePipelineService (transcribe, synthesize, formatForVoice)
+- `server/src/services/chat.ts` — chatService for conversation/message CRUD
+- `server/src/services/nexus-settings.ts` — telegramToken already in schema
+- `server/src/routes/voice.ts` — voice routes (pattern reference)
+
+### Established Patterns
+- Services as factory functions in server/src/services/
+- Routes in server/src/routes/
+- Onboarding wizard steps in ui/src/components/
+
+### Integration Points
+- `server/src/app.ts` — start telegram service conditionally when token present
+- `server/src/services/nexus-settings.ts` — read telegramToken
+- Onboarding wizard — add BotFather setup step
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — discuss phase skipped. Refer to ROADMAP phase description and success criteria.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discuss phase skipped.
+
+</deferred>