diff --git a/.env.example b/.env.example
index 07ec30a..b91cd3c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,27 +1,88 @@
-# LLM 모델 설정
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 율봇 환경 설정 예시 (.env.example)
+# 실제 사용 시 .env로 복사 후 값을 채워주세요.
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# ── LLM ──────────────────────────────────────────
 MODEL_ID=mlx-community/Qwen3-8B-4bit
 MAX_TOKENS=1024
-MAX_HISTORY_TURNS=30
-COMPACT_THRESHOLD=40
+MAX_HISTORY_TURNS=10        # 메모리에 유지할 최대 대화 턴 수
+COMPACT_THRESHOLD=20        # 이 턴 초과 시 오래된 대화를 LLM으로 자동 요약
+ENABLE_THINKING=true        # Thinking 모드 활성화 (Qwen3 지원)
+THINK_VERBOSE=false         # true 시 UI에 thinking 토큰 스트리밍
 
-# MySQL 설정 (미설정 시 DB 기능 비활성화)
+# ── MySQL ─────────────────────────────────────────
+# 미설정(DB_USER 빈 값) 시 DB 기능 전체 비활성화 (인메모리 모드)
 DB_HOST=localhost
 DB_PORT=3306
 DB_NAME=youlbot
 DB_USER=
 DB_PASSWORD=
 
-# LangSmith 트레이싱 (Phase 7) — https://smith.langchain.com 에서 API 키 발급
+# ── Qdrant ────────────────────────────────────────
+QDRANT_URL=http://localhost:6333
+QDRANT_COLLECTION=youlbot_docs
+
+# ── Embedding ────────────────────────────────────
+EMBEDDING_MODEL_ID=BAAI/bge-m3
+EMBEDDING_DEVICE=mps        # mps (Apple Silicon) | cpu | cuda
+
+# ── RAG 검색 ─────────────────────────────────────
+RAG_TOP_K=3                 # 최종 반환할 문서 청크 수
+RAG_VERBOSE=false           # true 시 검색 쿼리·청크 내용 출력
+RAG_SHOW_SOURCES=false      # true 시 답변 아래 출처(파일명·페이지) 표시
+LANGGRAPH_VERBOSE=false     # true 시 LangGraph 노드 전환 로그 출력
+
+# ── Semantic Chunker (Phase 13) ───────────────────
+SEMANTIC_BREAKPOINT_THRESHOLD_TYPE=percentile   # percentile | standard_deviation | interquartile | gradient
+SEMANTIC_BUFFER_SIZE=1      # 인접 문장 묶음 크기 (1=단일 문장)
+
+# ── Reranker (Phase 13-B) ────────────────────────
+RERANKER_ENABLED=false
+RERANKER_MODEL_ID=cross-encoder/mmarco-mMiniLMv2-L12-H384-v1  # 한국어 지원 다국어 모델
+RERANKER_FETCH_K=10         # rerank 전 후보 수 (RAG_TOP_K보다 커야 함)
+
+# ── Hybrid Search (Phase 18) — BM25 + Vector ─────
+# 활성화 후 기존 문서는 재수집 필요
+HYBRID_SEARCH_ENABLED=false
+SPARSE_MODEL_ID=Qdrant/bm25
+
+# ── Query Rewriting (Phase 19) ───────────────────
+QUERY_REWRITE_ENABLED=false
+
+# ── CRAG — 검색 결과 없을 때 web_search 자동 fallback (IDEA-5) ──
+CRAG_ENABLED=false
+
+# ── 대화 기반 자동 RAG 인덱싱 (IDEA-1) ───────────
+# 응답 완료 후 LLM이 유용한 정보 판단 → Qdrant 자동 저장 (background task)
+CONV_RAG_ENABLED=false
+
+# ── 지식 그래프 / GraphRAG (IDEA-8) ──────────────
+# add_relation / query_entity 도구 활성화 + 시스템 프롬프트 자동 주입
+GRAPH_ENABLED=false
+
+# ── REST API (Phase 22) ───────────────────────────
+# 빈 값이면 인증 없음 (개발 모드)
+API_TOKEN=
+
+# ── LangSmith 트레이싱 (Phase 7) ─────────────────
+# https://smith.langchain.com 에서 API 키 발급
 LANGCHAIN_TRACING_V2=false
 LANGCHAIN_API_KEY=
 LANGCHAIN_PROJECT=youlbot
 
-# Hybrid Search (Phase 18) — BM25 + Vector (활성화 후 기존 문서 재수집 필요)
-HYBRID_SEARCH_ENABLED=false
-SPARSE_MODEL_ID=Qdrant/bm25
+# ── 음성 인터페이스 (Phase 14) ────────────────────
+WHISPER_MODEL_SIZE=small    # tiny | base | small | medium | large
+TTS_VOICE=Yuna              # macOS say 명령어 한국어 음성 (Yuna | Siri 등)
 
-# Query Rewriting (Phase 19) — search_documents 호출 시 구어체 쿼리를 검색 최적화 쿼리로 변환
-QUERY_REWRITE_ENABLED=false
+# ── 멀티모달 이미지 이해 (Phase 17) ──────────────
+VISION_ENABLED=false
+VISION_MODEL_ID=mlx-community/Qwen2.5-VL-7B-Instruct-4bit
+VISION_MAX_TOKENS=512
 
-# REST API (Phase 22) — Bearer 토큰 인증. 빈 값이면 인증 없음(개발 모드)
-API_TOKEN=
+# ── 스마트 알림 / Telegram push (IDEA-2) ─────────
+# BotFather에서 봇 생성 후 토큰 입력
+TELEGRAM_BOT_TOKEN=
+# user_id → Telegram numeric chat_id 매핑 (JSON 형식)
+# 각 가족의 Telegram ID는 봇에 /start 전송 후 로그에서 확인
+TELEGRAM_USER_MAP={"아록": "", "근혜": "", "도율": "", "하율": ""}