Tag metadata tokens as {\"__meta\"} to separate TTS from progress messages

stream_response() now yields plain str for actual answer tokens and
{\"__meta\": str} dicts for progress/thinking/source metadata.
Consumers (WebUI, Telegram) can filter __meta tokens for TTS/display.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/ROADMAP.md

@@ -220,30 +220,36 @@ turns = conversation_repository.load_turns_after(self._conv_id, None, limit=10)
 
 ---
 
-## Phase 21 — Telegram Bot ★★☆
+## ✅ Phase 21 — Telegram Bot ★★☆
 
 **배경**: Gradio Web UI는 브라우저에서만 사용 가능. 텔레그램으로 이동 중에도 율봇과 대화하고 싶음.
 
-**구현 방식**: `AgentService`를 직접 임포트 — 별도 API 서버 없이 동일 머신에서 실행.
+**구현 방식**: youlbot REST API(Phase 22) 호출 — `youlbot-telegram/` 별도 프로젝트로 분리.
 
 ```
-telegram_bot.py
-├── Application (python-telegram-bot >= 20.0, async)
-├── /start, /reset CommandHandler
-├── MessageHandler → agent.stream_response() → message.edit_text() (타이핑 효과)
-└── Telegram user_id → youlbot user_id 매핑 (멀티유저 그대로 활용)
+youlbot-telegram/
+├── bot.py        ← Application (python-telegram-bot >= 20.0, async)
+│   ├── /start, /reset CommandHandler
+│   └── MessageHandler → api_client.chat() → edit_message_text() (타이핑 효과)
+├── api_client.py ← httpx 기반 REST API 클라이언트 (chat/reset)
+├── .env          ← TELEGRAM_BOT_TOKEN, YOULBOT_API_URL, 유저 ID 매핑
+└── requirements.txt
 ```
 
 **구현 내용**:
 - `python-telegram-bot>=20.0` (asyncio 기반)
-- `telegram_bot.py` — 새 진입점 (`python telegram_bot.py`로 실행)
-- `/start` — 환영 메시지 + 사용법 안내
-- `/reset` — 대화 이력 초기화 (`agent.reset()`)
-- 일반 메시지 → `agent.stream_response()` → 500자 단위 실시간 편집 (Telegram `edit_message_text`)
-- `telegram_user_id`를 `user_id`로 사용 → 기존 멀티유저·메모리·DB 구조 그대로 재사용
-- `.env` `TELEGRAM_BOT_TOKEN` 추가
+- `youlbot-telegram/bot.py` — 새 진입점 (`python bot.py`로 실행)
+- `/start` — 환영 메시지 + 매핑된 youlbot 사용자 이름 표시
+- `/reset` — `api_client.reset(user_id)` 호출로 대화 이력 초기화
+- 일반 메시지 → `api_client.chat()` SSE 스트리밍 → 0.6초 간격 실시간 편집
+- Telegram numeric ID → youlbot user_id `.env` 매핑 (`USER_아록_TELEGRAM_ID` 등)
+- 미등록 사용자에게 Telegram ID 안내 메시지 표시
 
-**제약**: 동일 머신에서만 실행 가능 (원격 실행은 Phase 22 REST API 필요)
+**실행 방법**:
+```bash
+cd youlbot-telegram
+python bot.py
+```
 
 **난이도**: 중간 | **임팩트**: 높음 (모바일·이동 중 접근)
 
@@ -292,7 +298,7 @@ async def ask_youlbot(message: str, user_id: str) -> str:
 
 ---
 
-## Phase 23 — WebUI 분리 (youlbot-webui 별도 프로젝트) ★★☆
+## ✅ Phase 23 — WebUI 분리 (youlbot-webui 별도 프로젝트) ★★☆
 
 **배경**: 현재 `app.py`(Gradio)는 `container.py`를 직접 import해 서비스를 사용한다.
 REST API(Phase 22)를 완성했으므로, WebUI를 독립 프로젝트로 분리해 API만 호출하도록 변경한다.
@@ -401,8 +407,8 @@ docker-compose.yml
 ```
 단기 (1~2주)                  중기 (1개월)              장기
 ────────────────────────     ──────────────────────    ──────────────────
-Phase 21 Telegram Bot     →  Phase 20 RAGAS 평가    →  Phase 16 (Docker)
-                          →  Phase 15 (모델선택)    →  Phase 17 (멀티모달)
+Phase 20 RAGAS 평가       →  Phase 15 (모델선택)    →  Phase 16 (Docker)
+                                                    →  Phase 17 (멀티모달)
 ```
 
 ### 우선순위 매트릭스
@@ -427,8 +433,9 @@ Phase 21 Telegram Bot     →  Phase 20 RAGAS 평가    →  Phase 16 (Docker)
 | Phase 13-B Reranker | ✅ 완료 | — | — | — |
 | Phase 18 Hybrid Search | ✅ 완료 | — | — | — |
 | Phase 19 Query Rewriting | ✅ 완료 | — | — | — |
-| Phase 21 Telegram Bot | 🔲 신규 | 중간 | 높음 | ⭐ 1순위 (REST API 활용) |
+| Phase 21 Telegram Bot | ✅ 완료 | — | — | — |
 | Phase 22 REST API | ✅ 완료 | — | — | — |
+| Phase 23 WebUI 분리 | ✅ 완료 | — | — | — |
 | Phase 20 RAGAS 평가 | 🔲 신규 | 중간 | 중간 | 3순위 |
 | Phase 15 모델 선택 | 🔲 미완 | 중간 | 중간 | 4순위 |
 | Phase 16 Docker | 🔲 미완 | 높음 | 중간 | 5순위 |