diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7ef2e1a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,201 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+---
+
+## 프로젝트 개요
+
+**라온누리 (Raonnuri)** - 초등학생 대상 창작 글쓰기 교육 플랫폼
+
+**Tech Stack**: Next.js 16, React 19, Chakra UI v3, Firebase Auth, TypeScript
+
+---
+
+## 개발 명령어
+
+```bash
+npm run dev # 개발 서버 (포트 3001, webpack 사용)
+npm run build # 프로덕션 빌드
+npm run lint # ESLint 실행
+npx tsc --noEmit # 타입 체크 (빌드 전 필수)
+```
+
+**주의**:
+- Dev server는 포트 3001 사용
+- React Compiler 활성화
+- 커밋 전 타입 체크 필수 (`npx tsc --noEmit`)
+
+---
+
+## 핵심 아키텍처
+
+### Manager Pattern (필수)
+
+**모든 데이터 작업은 Manager 사용 (서비스 직접 호출 금지)**
+
+```typescript
+import { teamManager, userManager } from "@/managers";
+
+// ✅ Good
+const teams = await teamManager.getMyTeams();
+const users = await userManager.getUsersByTeam(teamId);
+
+// ❌ Bad - 서비스 직접 호출 금지
+```
+
+**Available Managers**:
+- `teamManager` - Team CRUD, member management, security level
+- `userManager` - User CRUD
+- `draftManager` - localStorage + Realtime DB 하이브리드
+- `writingSessionManager` - Real-time monitoring
+- `writingManager`, `topicManager`, `feedManager`
+
+**상세**: `API_SPEC.md` 참조
+
+---
+
+### Data Model 핵심 원칙
+
+**Firebase Auth = Single Source of Truth** (이름, 이메일, 사진)
+
+- Firestore Users 컬렉션: `uid`, `createdAt`, `lastLoginAt`, `settings`만 저장
+- UI User 객체: Firebase Auth + Firestore 자동 결합
+- 팀별 닉네임: `team.members[uid].nickname` (User 아님)
+- 멤버 확인: `uid in team.members`
+
+**상세**: `DATA_MODELS.md` 참조
+
+---
+
+## 필수 개발 규칙
+
+### 다국어 지원 (i18n)
+
+**모든 새로운 UI 및 페이지는 다국어 지원이 필수입니다.**
+
+```typescript
+// ✅ Good
+import {useTranslations} from "next-intl";
+import {useRouter} from "@/i18n/routing";
+
+const t = useTranslations('newPage');
+return {t('title')} ;
+
+// ❌ Bad
+return 새 페이지 ; // 하드코딩 금지!
+```
+
+**상세**: `I18N_GUIDE.md` 참조
+
+---
+
+### 스타일 가이드
+
+**버튼에는 항상 `colorPalette="brand"` 사용**:
+
+```tsx
+// ✅ Good
+클릭
+
+// ❌ Bad
+클릭 // 기본 gray 사용 금지
+```
+
+**Semantic 토큰 우선 사용** (숫자/하드코딩 금지):
+- `color="fg"` / `color="fg.muted"`
+- `bg="bg"` / `bg="brand.subtle"`
+- `borderColor="border.muted"`
+
+**Icon 규칙**: react-icons 필수 (이모티콘 금지)
+- ✅ `react-icons/lu` (Lucide) - 메인 아이콘 세트
+- ❌ 이모티콘 (🌍📝) - 사용 금지
+
+**상세**: `STYLE_GUIDE.md` 참조
+
+---
+
+### API 개발 규칙
+
+**RESTful 원칙**: HTTP Method로 동작 구분
+
+```
+POST /api/resource → 생성/추가
+DELETE /api/resource → 삭제/제거
+PUT /api/resource → 전체 수정
+GET /api/resource → 조회
+```
+
+**Firebase Admin SDK**: `adminFbClient` 싱글톤 사용
+
+```typescript
+// ✅ Good
+import {adminFbClient} from "@/lib/firebase-admin";
+const doc = await adminFbClient.collection('users').doc(uid).get();
+
+// ❌ Bad
+import {getFirestore} from "firebase-admin/firestore";
+const db = getFirestore(); // 초기화 문제 발생 가능
+```
+
+**API 응답**: 헬퍼 함수 필수
+
+```typescript
+import {successResponse, validationErrorResponse} from "@/lib/api-response";
+
+// ✅ Good
+return successResponse({ data });
+return validationErrorResponse("에러 메시지");
+
+// ❌ Bad
+return NextResponse.json({success: false, ...});
+```
+
+**상세**: `API_SPEC.md` 참조
+
+---
+
+### 보안
+
+**초대 링크 기반 팀 참여**: 디스코드 스타일 초대 시스템 사용
+- 모든 유저는 로그인 필수 (익명 인증 삭제됨)
+- 팀 참여는 초대 링크를 통해서만 가능
+- 닫힌 팀 → 초대 안 만들면 됨
+
+**XSS 방지**: 백엔드 자동 sanitize
+- `src/lib/server/writing.ts`에서 모든 HTML 자동 세탁
+- 프론트엔드 별도 처리 불필요
+
+**상세**: `SECURITY.md` 참조
+
+---
+
+## Documentation Requirements
+
+**모든 새 기능/페이지는 다음 3개 파일 업데이트 필수**:
+
+1. `PROJECT_STRUCTURE.md` - 페이지 구조, 컴포넌트 목록
+2. `ROADMAP.md` - 완료 작업, 예정 작업
+3. `TECH_STACK.md` - 아키텍처 패턴, 플로우 다이어그램
+
+---
+
+## 참조 문서
+
+### 개발 가이드
+- **`API_SPEC.md`** - API 명세서, RESTful 원칙, Firebase Admin SDK
+- **`STYLE_GUIDE.md`** - Color 사용법, Icon 규칙, Chakra UI 테마
+- **`FRONTEND_DESIGN_PATTERNS.md`** - 컴포넌트 디자인 철학, 인터랙션/시각/애니메이션 패턴
+- **`I18N_GUIDE.md`** - 다국어 지원 가이드 (필수)
+- **`DEVELOPMENT_GUIDE.md`** - AI Delta 전송, Draft 저장, Firebase Functions
+
+### 프로젝트 문서
+- **`PROJECT_STRUCTURE.md`** - 프로젝트 구조
+- **`TECH_STACK.md`** - 기술 스택, 아키텍처
+- **`DATA_MODELS.md`** - 데이터베이스 스키마
+- **`SECURITY.md`** - 보안 정책, 3단계 보안 레벨
+- **`ROADMAP.md`** - 개발 로드맵
+
+---
+
+© 2024 BlueNovaLab. All rights reserved.
\ No newline at end of file
diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md
index 9da81f3..28c644e 100644
--- a/PROJECT_STRUCTURE.md
+++ b/PROJECT_STRUCTURE.md
@@ -1,10 +1,25 @@
# 라온누리 - 프로젝트 구조
-> 최종 업데이트: 2026-03-27 (학생/교사 로그인 분리)
+> 최종 업데이트: 2026-06-04 (스튜디오 플로우 UI 통합 리디자인)
초등학생을 위한 창작 글쓰기 교육 플랫폼
-**최신 업데이트** (2026-03-27):
+**최신 업데이트** (2026-06-02):
+- **스튜디오 6단계 선형 글쓰기 플로우** (`/write/studio`) - "그림으로 시작 → 글 완성"을 한 페이지에서 진행하는 신규 라우트
+ - **단일 페이지 상태머신**: `page.tsx` 오케스트레이터(useReducer)가 단일 진실 공급원(StudioFlowState)을 보유, 7개 스테이지 컴포넌트를 순차 렌더
+ - **6단계 흐름**: S0 안내(intro) → S1 업로드(upload) → S2 1차 작문(firstWriting) → S3 보상① 인터랙션(rewardInteraction) → S4 2차 작문(secondWriting) → S5 보상② 이펙트(rewardEffect) → S6 완료(complete)
+ - **S1 키워드 추출**: 종이 그림 촬영/업로드 → AI가 그림에서 키워드 5개 추출 (`POST /api/studio/analyze`)
+ - **S2 1차 작문**: 그림 + 키워드 5개 + 역할별 자유 3문장(상황/감정/이유, 한 문장씩 자유 작성) (학생 단독, AI 없음), 문장 구조는 플랫폼 비고정 — 선생님 직접 교육 + 역할별 예문·전구 안내로 지도(주제 연동 시 주제 데이터로 대체 예정), S2→S3 전환 시 draft Writing 생성(createWriting) + 이미지 업로드(uploadUserImage)
+ - **S3/S5 보상**: 공용 `RewardCanvasEditor`로 인터랙션(움직임) 1개 / 스프라이트 이펙트 1개 부여 (영역 1개 제한, `useDistortionEditor` 기반)
+ - **S4 글 다듬기**: AI 띄어쓰기 교정 + 의미 단위 낱말 분해 (`POST /api/studio/segment`) → 낱말 교체·자리 삽입 추천 (`POST /api/studio/suggest`), 낱말 칩 탭/+자리로 편집 (SentenceTokenEditor)
+ - **S6 완료**: 1회차 수업 종료 → draft를 발행(published)으로 마감 (`POST /api/studio/complete`)
+ - **공용 컴포넌트**: `StageStepper`(6단계 가로 진행 표시기, 점수/숫자 미표시), `RewardCanvasEditor`(인터랙션/이펙트 공용)
+ - **데이터**: writings 컬렉션에 `keywords`, `studioResult`(sentencesV1/V2, blanks, grantedInteraction/Effect, completedAt) 저장, 보상은 distortionAreas/spriteEffectAreas, status draft→published, rewardType `participation`
+ - **진입점**: `/write` 모드 선택 화면에 스튜디오 진입 카드 추가
+ - **다국어 지원**: `studio` 네임스페이스, `pageTitles.writeStudio` (ko/en/ja)
+ - **레거시 공존**: 기존 글쓰기 라우트(`/write/fill-in-blank`, `/write/image`, `/write/easy`)와 병행 운영, 추후 제거 예정
+
+**이전 업데이트** (2026-03-27):
- **학생/교사 역할 분리** - 로그인/가입 시 학생/교사 탭 선택, 역할별 홈 페이지 분리
- **역할 시스템**: `UserRole` (student/teacher), Firebase Auth Custom Claims, Firestore `role` 필드
- **교사 승인 워크플로우**: 가입 → 승인 대기 → 관리자 승인/거절 → 로그인 가능
@@ -546,7 +561,8 @@
| **교사 승인 대기** | `/[locale]/teacher/pending-approval` | 교사 승인 대기 화면 | 승인 대기/거절 상태, 상태 확인, 로그아웃 | ✅ 완료 |
| **내 글 모음** | `/[locale]/writings` | 🆕 **전체 글 목록 페이지** | 🆕 **사용자의 모든 글 표시 (Grid)** 으로 필요한 props만 전달
+ ▼
+┌──────────────────────────────────────────────────────────┐
+│ 스테이지 컴포넌트 src/app/[locale]/write/studio/_stages/ │
+│ IntroStage · UploadStage · FirstWritingStage · │
+│ RewardInteractionStage · SecondWritingStage · │
+│ RewardEffectStage · CompletionStage │
+│ (상태/부수효과 없음 — 입력 수집 + 콜백 호출만) │
+└──────────────────────────────────────────────────────────┘
+ │ 보상 단계(S3/S5)는 공용 편집기 사용
+ ▼
+┌──────────────────────────────────────────────────────────┐
+│ 공용 컴포넌트 │
+│ src/components/ui/StageStepper.tsx (6단계 진행 표시기) │
+│ src/components/writing/studio/RewardCanvasEditor.tsx │
+│ - mode: "interaction" | "effect" 로 S3/S5 공용 │
+│ - useDistortionEditor 기반, 영역 1개 제한 (AREA_CAP=1) │
+└──────────────────────────────────────────────────────────┘
+```
+
+**계약 파일**: `src/app/[locale]/write/studio/_flow/types.ts` — `StudioFlowState`(전역 상태) / `StudioStageProps`(스테이지 prop 시그니처) / `deriveBlankValues()` 헬퍼.
+
+#### S0 → S6 단계 흐름
+
+```
+S0 intro 오프라인에서 종이에 그림 그리기 안내 (앱 외부 활동)
+ ↓ goNext()
+S1 upload 그림 촬영/업로드 → AI 키워드 5개 추출
+ ↓ runAnalyze() → POST /api/studio/analyze
+S2 firstWriting 그림 + 키워드 5개 + 역할별 자유 3문장 (학생 단독, AI 없음)
+ · situation: 상황 — 언제/어디서 무슨 일이 있었는지 (자유 1문장)
+ · emotion: 감정 — 그때 어떤 마음이었는지 (자유 1문장)
+ · reason: 이유 — 왜 그런 마음이 들었는지 (자유 1문장)
+ · 문장 구조를 플랫폼이 고정하지 않음(선생님 직접 교육). 역할별 예문 + 전구 안내로만 지도. 주제 연동 시 예문/안내는 주제 데이터로 대체 예정(현재 i18n 하드코딩)
+ ↓ createDraft(): 입력 검증 → writingManager.createWriting(status:'draft')
+ ↓ + uploadUserImage() + 1차 문장을 2차 작문 초기값으로 시드
+S3 rewardInteraction 인터랙션(움직임) 1개 부여 → 적용 (RewardCanvasEditor, 영역 1개)
+ ↓ onInteractionApplied() → updateDistortionAreas()
+S4 secondWriting 3문장 다듬기 — AI 띄어쓰기 교정 + 낱말 분해 → 낱말 교체·자리 삽입 추천 (낱말 칩 편집)
+ ↓ 진입 시 fetchSegmentation() → POST /api/studio/segment (분해 후) fetchSuggestions() → POST /api/studio/suggest
+S5 rewardEffect 스프라이트 이펙트 1개 부여 → 적용 (RewardCanvasEditor, 영역 1개)
+ ↓ onEffectApplied() → updateDistortionAreas()
+S6 complete 1회차 수업 종료 → onComplete() → POST /api/studio/complete (발행)
+```
+
+#### AI 엔드포인트 4개
+
+| API | 경로 | AI | 역할 |
+|-----|------|----|------|
+| **분석** | `POST /api/studio/analyze` | ✅ | 그림 분석(analyzeImage 재사용) → 키워드 5개 + ImageAnalysisResult |
+| **분해** | `POST /api/studio/segment` | ✅ | S4: 3문장 → 띄어쓰기 교정 + 의미 단위 낱말 분해 (낱말 텍스트 그대로, 글자 변조 금지 가드) |
+| **추천** | `POST /api/studio/suggest` | ✅ | S4: 분해된 낱말 → 낱말 교체 추천 + 자리 삽입 추천 (분해와 분리된 별도 호출) |
+| **완료** | `POST /api/studio/complete` | ❌ | draft→published 발행, studioResult 저장, HTML sanitize |
+
+**서비스 레이어**: `src/services/studioService.ts`
+- `extractStudioKeywords(imageBase64, mimeType, locale)` — imageAnalysisService.analyzeImage 재사용, suggestedKeywords→(부족 시)objects 순으로 정확히 5개 확정 (패딩 없음)
+- `segmentSentences(sentences, locale)` — AI가 의미 단위 낱말 덩어리로 반환 → 결정적 분해/조립, `stripSpaces` 무결성 가드 통과 시 채택, 실패 시 공백 분리 폴백
+- `suggestReplacements(sentences, keywords, locale)` — generateContent + Response Schema, 문장별 `{replacements, insertions}`(교체·삽입) 클램프/정제, 실패 시 빈 추천 폴백
+- 사용량 메타데이터(`_ai`)는 라우트로 그대로 전달 → 라우트가 logAIUsage 기록
+
+**프롬프트**: `src/prompts/studio/templates.ts`(역할별 자유 슬롯 — STUDIO_BLANK_IDS/getStudioBlanks/composeStudioSentences/studioBlankId), `src/prompts/studio/segmentation.ts`·`suggestion.ts`(ko/en/ja)
+
+#### 데이터 / 영속화 모델
+
+draft를 먼저 만들고(S2→S3) 단계별로 갱신한 뒤 S6에서 발행하는 점진적 저장 모델.
+
+```typescript
+// src/types/writing.ts (스튜디오 모드에서만 사용)
+interface Writing {
+ // ...기존 필드
+ keywords?: string[]; // 🆕 그림에서 추출한 키워드 5개
+ studioResult?: StudioResult; // 🆕 스튜디오 플로우 결과
+}
+
+// src/types/studio.ts
+interface StudioResult {
+ keywords: string[];
+ sentencesV1: Record; // 1차 작문 (학생 단독)
+ sentencesV2: Record; // 2차 작문 (AI 도움, 최종 본문)
+ blanks: StudioBlank[];
+ grantedInteraction: boolean; // S3 보상 적용 여부
+ grantedEffect: boolean; // S5 보상 적용 여부
+ completedAt: string; // ISO 8601
+}
+```
+
+**저장 위치별 정리**:
+- **writings 컬렉션**: `keywords`, `studioResult`(sentencesV1/V2·blanks·grantedInteraction/Effect·completedAt)
+- **보상**: 인터랙션/이펙트는 `distortionAreas` / `spriteEffectAreas` (S3/S5에서 클라이언트가 저장, complete API는 건드리지 않음)
+- **상태 전이**: `status` draft → published (최초 발행 시 주제 usageCount 1회 증가)
+- **보상 분류**: `rewardType: 'participation'`
+- **하드닝**: complete API에서 본문 HTML sanitize + studioResult 자유 입력값은 태그 제거 후 평문 저장
+
+#### 진입점 및 i18n
+
+- **진입 카드**: `/write` 모드 선택 화면 상단에 스튜디오 진입 카드 추가 (`router.push("/write/studio")`)
+- **다국어**: `studio` 네임스페이스(stepper/actions/error/단계별 키), `pageTitles.writeStudio` (ko/en/ja)
+- **접근 제어**: `useRequireAiAccess()` + `useAiIpCheck()` (AI 사용 가능 검증)
+
+#### 공용 프리미티브 / 통합 비주얼 언어 (2026-06-04)
+
+전 단계가 **하나의 카드/헤더/애니메이션 시스템**을 공유하도록 `src/components/writing/studio/`에 표현 전용(presentational) 공용 프리미티브를 정리했다. 스테이지는 레이아웃 코드를 직접 들지 않고 이 프리미티브만 조합한다.
+
+- **`StudioCard`** — 단계 공용 콘텐츠 카드 (tone default/muted/brand, cascade index 진입 애니메이션)
+- **`StudioStageHeader`** — 원형 아이콘 + 제목 + 부제 헤더 (전 단계 통일)
+- **`RolePill` + `studioRoleMeta`** — 상황/마음/까닭 역할 식별(아이콘+라벨), S2·S4 공용
+- **`StudioImageCard`** — 고정 비율 이미지 카드 (선택적 children, 예: 키워드 칩)
+- **`RewardBanner`** — S3/S5 보상 축하 배너 공용
+- **`SentenceTokenEditor` + `sentenceTokens`** — S4 낱말 칩 편집기 (낱말 탭→교체 Popover, +자리→삽입 Popover, 갱신 낱말 그라디언트 표시) + 토큰 조립/폴백 유틸
+- **`studioMotion`** — 공용 `@keyframes`(studioFadeIn/Pop/Breathe/EmptyBreathe) + `STUDIO_REDUCED_MOTION`(prefers-reduced-motion 게이트)
+- **S2 자유 작성**: 고정 빈칸 템플릿(FillBlankSentence) 제거 → FirstWritingStage가 역할별 자유 Textarea + 전구 안내 + 예문을 직접 렌더
+- **i18n 추가**: `studio` 네임스페이스에 `roles.{situation,emotion,reason}`, `firstWriting.{freePlaceholder,examplesLabel,guides.*,examples.*}`, `rewardInteraction.tip`, `rewardEffect.tip`, `reward.{controlsTitle,dragHint,applyButton}`, `secondWriting.*`(낱말 편집 키) (ko/en/ja)
+
+#### 참고 파일
+
+- `src/app/[locale]/write/studio/page.tsx` - 오케스트레이터 (useReducer 상태머신)
+- `src/app/[locale]/write/studio/_flow/types.ts` - StudioFlowState / StudioStageProps
+- `src/app/[locale]/write/studio/_stages/*.tsx` - 7개 스테이지 컴포넌트
+- `src/components/ui/StageStepper.tsx` - 6단계 진행 표시기
+- `src/components/writing/studio/RewardCanvasEditor.tsx` - 인터랙션/이펙트 공용 편집기
+- `src/components/writing/studio/{StudioCard,StudioStageHeader,RolePill,StudioImageCard,RewardBanner,SentenceTokenEditor}.tsx` + `{sentenceTokens,studioMotion,studioRoleMeta}.ts` - 공용 프리미티브 (통합 비주얼 언어)
+- `src/services/studioService.ts` - extractStudioKeywords / segmentSentences / suggestReplacements
+- `src/app/api/studio/{analyze,segment,suggest,complete}/route.ts` - AI 엔드포인트 4개
+- `src/prompts/studio/{templates.ts,segmentation.ts,suggestion.ts}` - 프롬프트
+- `src/types/studio.ts` - 플로우 타입, `src/types/writing.ts` - keywords?/studioResult?
+
+---
+
## 참고 문서
- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - 프로젝트 구조