[Documenter] #215 Reference + guide + design Approved

- docs/reference/215-ai-frame-suggest.md — v0.2.0 모듈/함수/Riverpod/meta_kv 사양
- docs/guides/ai-help-onboarding.md — AI 도움 켜기/끄기 사용자 가이드
- docs/design/215-gemma-frame-suggest/{README,fn-suggest_frame,fn-model_lifecycle}
  상태 Draft → Approved, 추적성 헤더에 실제 구현 파일/테스트 경로 + 레퍼런스/가이드 cross-link
- docs/README.md — 현재 발행된 문서 인덱스 섹션 추가

Refs #215

docs/design/215-gemma-frame-suggest/README.md

@@ -1,10 +1,32 @@
 # 설계서: Phase 2-A — Gemma 4 on-device 프레임 자동 생성 (#215)
 
-> **상태**: Draft
-> **작성**: [AI] Architect · **최종수정**: 2026-06-12
-> **추적성** — Redmine: #215 · 관련 ADR: [ADR-0003 on-device LLM Gemma](../../adr/0003-on-device-llm-gemma.md)
-> · 구현 파일: `app/lib/data/ai/`, `app/lib/domain/ai/`, `app/lib/state/ai_providers.dart` (TBD by Developer)
-> · 테스트: `app/test/domain/ai/`, `app/test/data/ai/` (TBD by Developer)
+> **상태**: Approved (v0.2.0, 커밋 `0d1db2d`)
+> **작성**: [AI] Architect · **최종수정**: 2026-06-12 (Documenter)
+> **추적성** — Redmine: #215 · 관련 ADR: [ADR-0003 on-device LLM Gemma](../../adr/0003-on-device-llm-gemma.md) · 릴리스 태그: `v0.2.0`
+> · 구현 파일:
+>   - `app/lib/data/ai/llm_service.dart` (abstract + MockLlmService)
+>   - `app/lib/data/ai/gemma_llm_service.dart` (stub — OQ-1 후 활성)
+>   - `app/lib/data/ai/model_lifecycle.dart` (download/verify/purge)
+>   - `app/lib/domain/ai/frame_candidate.dart`
+>   - `app/lib/domain/ai/suggest_frame.dart`
+>   - `app/lib/domain/ai/few_shot_builder.dart`
+>   - `app/lib/domain/ai/parse_response.dart`
+>   - `app/lib/state/ai_providers.dart` (Riverpod providers + ModelDownloadController)
+>   - `app/lib/ui/screens/settings_screen.dart`
+>   - `app/lib/ui/widgets/frame_suggestion_dialog.dart`
+>   - `app/lib/ui/screens/habit_create_screen.dart` (`_AiSuggestButton`)
+> · 테스트:
+>   - `app/test/domain/ai/{suggest_frame,few_shot_builder,parse_response}_test.dart`
+>   - `app/test/data/ai/model_lifecycle_test.dart`
+>   - `app/test/state/model_download_controller_test.dart`
+>   - `app/test/ui/ai_suggest_button_visibility_test.dart`
+> · 레퍼런스: [docs/reference/215-ai-frame-suggest.md](../../reference/215-ai-frame-suggest.md)
+> · 사용 가이드: [docs/guides/ai-help-onboarding.md](../../guides/ai-help-onboarding.md)
+>
+> **알려진 follow-up** (Reviewer F1/F2 + OQ-1):
+> - OQ-1: 실제 Gemma 4 E2B Q4_0 모델 URL + SHA-256 — 현재 placeholder (`example.invalid`).
+> - F1: 60초 idle auto-unload 미구현 — stub 상태라 무의미. OQ-1 해결 시 추가.
+> - F2: `ModelLifecycle.purge()` 의 `File.delete()` try/catch 미감쌈 — placeholder URL 라 도달 불가.
 > **하위 문서**:
 > - [fn-suggest_frame.md](./fn-suggest_frame.md) — Gemma 4 호출 + few-shot 조립 + 응답 파싱
 > - [fn-model_lifecycle.md](./fn-model_lifecycle.md) — 모델 다운로드 / 로드 / 언로드 / 삭제 + LlmService 인터페이스

docs/design/215-gemma-frame-suggest/fn-model_lifecycle.md

@@ -1,7 +1,8 @@
 # 함수 설계서: `ModelLifecycle` + `LlmService` (#215)
 
-> **부모 설계서**: ./README.md · **상태**: Draft
-> **작성**: [AI] Architect · **구현**: `app/lib/data/ai/model_lifecycle.dart`, `llm_service.dart`, `gemma_llm_service.dart` (TBD) · **테스트**: `app/test/data/ai/{model_lifecycle,gemma_llm_service}_test.dart` (TBD)
+> **부모 설계서**: ./README.md · **상태**: Approved (v0.2.0)
+> **작성**: [AI] Architect · **구현**: `app/lib/data/ai/model_lifecycle.dart`, `llm_service.dart`, `gemma_llm_service.dart` (stub) · **테스트**: `app/test/data/ai/model_lifecycle_test.dart` + `app/test/state/model_download_controller_test.dart` (총 10 케이스)
+> · 동기화 노트: `GemmaLlmService` 는 모든 메서드가 `UnimplementedError` 를 던지는 stub 상태 — OQ-1 (실 모델 URL+SHA) 해결 시 활성. v1 런타임은 `MockLlmService` 가 `llmServiceProvider` 에 주입.
 
 > 본 문서는 모델 수명주기와 추론 인터페이스를 묶어 다룬다. 모두 I/O 경계 — flutter_gemma + 파일시스템 + 네트워크 + 네이티브 메모리.
 

docs/design/215-gemma-frame-suggest/fn-suggest_frame.md

@@ -1,7 +1,7 @@
 # 함수 설계서: `suggestFrame` + `buildFewShotPrompt` + `parseFrameCandidates` (#215)
 
-> **부모 설계서**: ./README.md · **상태**: Draft
-> **작성**: [AI] Architect · **구현**: `app/lib/domain/ai/suggest_frame.dart`, `few_shot_builder.dart`, `parse_response.dart` (TBD) · **테스트**: `app/test/domain/ai/{suggest_frame,few_shot_builder,parse_response}_test.dart` (TBD)
+> **부모 설계서**: ./README.md · **상태**: Approved (v0.2.0)
+> **작성**: [AI] Architect · **구현**: `app/lib/domain/ai/suggest_frame.dart`, `few_shot_builder.dart`, `parse_response.dart` · **테스트**: `app/test/domain/ai/{suggest_frame,few_shot_builder,parse_response}_test.dart` (총 27 케이스)
 
 > 본 문서는 도메인 핵심 알고리즘 함수 3개를 묶어 다룬다. 셋 다 순수 함수 (또는 LlmService 만 의존) 로 테스트 가능성을 우선한다.