diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..9a64e35
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,48 @@
+# Changelog
+
+본 프로젝트의 모든 의미있는 변경은 본 파일에 기록한다.
+형식: [Keep a Changelog](https://keepachangelog.com/) · 버전: [SemVer](https://semver.org/).
+
+## [0.2.0] — 2026-06-12
+
+### Added — Phase 2-A: On-device Gemma 4 frame suggestion (Redmine #215)
+- `LlmService` 추상 인터페이스 + `MockLlmService` (테스트/v1 런타임 주입) + `GemmaLlmService` stub (OQ-1 시점 활성화).
+- `ModelLifecycle` — Range 기반 재개 가능 다운로드 + SHA-256 검증 + opt-out 즉시 삭제.
+- `ModelDownloadController` (Riverpod `StateNotifier`) — start / pause / resume / cancel.
+- 도메인 함수 `suggestFrame` + `buildFewShotPrompt` + `parseFrameCandidates` (모두 순수, graceful — 실패 시 빈 리스트).
+- `FrameSuggestionDialog` — L2/L3 후보 카드 + 컬러 배지.
+- `SettingsScreen` 신규 — AI 도움 토글 (기본 OFF, 옵트인 시 동의 다이얼로그 → 다운로드 시작), 진행률 + 일시정지/재개/취소, 옵트아웃 시 즉시 purge + 해제 공간 토스트.
+- `HabitCreateScreen` 의 "AI 제안" 버튼 3분기 (hidden / visible+disabled+tooltip / enabled).
+- ADR-0003 — on-device LLM Gemma 도입 결정 + 5 대안 기각.
+- 설계서 `docs/design/215-gemma-frame-suggest/` (README + fn-suggest_frame + fn-model_lifecycle).
+- 신규 31 테스트 (parse 8 + few_shot 7 + suggest 12 + lifecycle 7 + AC2 state 3 + AC6 widget 4).
+- 9/10 AC PASS — AC10 (한국어 평가 corpus ≥70%) DEFER → OQ-1 해결 후 수행.
+
+### Architecture
+- `lib/data/ai/` (I/O 경계) ↔ `lib/domain/ai/` (순수 도메인) 분리.
+- `meta_kv` 5 키 추가 (`ai_opt_in` / `ai_model_path` / `ai_model_sha256` / `ai_download_state` / `ai_download_bytes`) — schema migration 0.
+- 프라이버시: 사용자 raw text 단말 밖 송출 0. 추론 100% 단말.
+
+### Known limitations
+- **OQ-1 미해결**: 실제 Gemma 4 E2B Q4_0 모델 URL + SHA-256 미확정. `_kModelUrlPlaceholder` / `_kModelShaPlaceholder` 상태. v1 런타임은 `MockLlmService` 주입 — opt-in 토글 시 다운로드는 placeholder URL 로 실패 (graceful 처리).
+- **F1**: 60초 idle auto-unload 미구현 (현재 stub 라 무의미).
+- **F2**: `ModelLifecycle.purge()` 의 `File.delete()` try/catch 미감쌈 (placeholder URL 라 도달 불가).
+- 위 3건 모두 OQ-1 후속 이슈에서 처리.
+
+### Polish (Designer)
+- 다운로드 타일 상태 라벨 + 컬러 텍스트 + 라운드 progress bar + `FilledButton.tonalIcon` 재개/재시도.
+- `_friendlyError()` — 내부 코드 (`network:` / `http ` / `stream:` / `sha mismatch`) 를 한국어 다음행동 문구로 매핑.
+- 옵트인/아웃 다이얼로그 `_Bullet` 위젯으로 정렬.
+- `FrameCandidate` 카드에서 confidence% 표기 제거 (내부값).
+
+---
+
+## [0.1.0] — 2026-06-12 (retro-tagged)
+
+### Added — Phase 1 MVP (Redmine #204)
+- Flutter 3.x + Drift 21 테이블 (habits, habit_variants, checkins, ladders, frame_patterns, reward_menu_items, references, protocols, methodologies, diet_patterns ...).
+- 도메인 함수 6개 (validateFrameLevel / judgeActiveHabitQuota / computeStreak / 등).
+- UI 화면 4개 (HabitListScreen / HabitCreateScreen / CheckinScreen / RewardListScreen).
+- 시드 데이터 8 JSON (refs 84 / protocols 34 / break 8 / common 5 / methodology 21 / frame 30 / reward 30 / diet 5).
+- ADR-0001 (dose_variants 도입) + ADR-0002 (정규화 방식).
+- 62 테스트 통과.
diff --git a/app/pubspec.yaml b/app/pubspec.yaml
index 86a644b..1ef5a4a 100644
--- a/app/pubspec.yaml
+++ b/app/pubspec.yaml
@@ -1,7 +1,7 @@
 name: life_helper
 description: "Huberman + Atomic Habits + Tiny Habits + If-Then. Local-first habit/checklist/todo."
 publish_to: 'none'
-version: 0.1.0+1
+version: 0.2.0+2
 
 environment:
   sdk: ^3.12.2