Stabilize runtime auth and E2E coverage

docs/HANDOFF.md

@@ -1,63 +1,270 @@
-# Vignette 핸드오프 노트
+# Vignette Handoff
 
-> 2026-06-26 02:0x KST · 세션 b00bd7f3 → 다음 세션. **새 세션은 이 파일부터 읽고 이어받는다.**
+> Updated: 2026-06-26 14:43 KST. 새 세션은 이 문서와 `docs/DESIGN_CONCEPT.md`를 먼저 읽고 이어가면 된다.
 
-## 프로젝트
-한신대 SW중심대학 산학협력 — 생성형 AI 심리상담 시뮬레이션 훈련 플랫폼 **Vignette**.
-- repo: `D:\workspace\vignette` · github.com/yunchan8804-blip/vignette (**master, f869d25**)
-- 학습자가 가상 내담자(AI 페르소나)와 상담 연습 → 백그라운드 평가 AI가 기법 라벨링·피드백. 3역할(학습자/교수자/관리자).
+## 현재 상태
 
-## 라이브 URL
-- **프론트(공개)**: https://vignette.chanpaca.net (= vignette-b1q.pages.dev, Cloudflare Pages)
-- **API(터널)**: https://api-vignette.chanpaca.net (cloudflared named tunnel → localhost:8000)
-- 라이브 경로: 로그인(학습자) → 학습자홈 → **연습 시작** → 상담세션 → **회기 시작** → 입력창 말걸기 → 서연(P1) 실응답
+- Workspace: `D:\workspace\vignette`
+- 로컬 웹 기본 포트: `http://localhost:5173`
+- 로컬 API 기본 포트: `http://127.0.0.1:8000`
+- 로컬 engine gateway 기본 포트: `http://127.0.0.1:9099`
+- 공개 웹: `https://vignette.chanpaca.net`
+- 공개 API: `https://api-vignette.chanpaca.net`
+- Google OAuth 허용 이메일 도메인: `hs.ac.kr`, `twentyoz.kr`
+- `frontenddesign` 스킬은 현재 세션의 사용 가능 스킬 목록에 없었다. 대신 `docs/DESIGN_CONCEPT.md`를 SSOT로 사용했다.
+- 공개 API 터널은 현재 `C:\Users\encep\.cloudflared\vignette-config.yml`에서 `http://127.0.0.1:8001`을 본다.
+- 공개용 API 프로세스는 `127.0.0.1:8001`에서 `ENVIRONMENT=prod`로 떠 있다. 로컬 개발 API `127.0.0.1:8000`은 `dev`로 유지했다.
+- `GET /personas`는 이제 인증 필요다. 로컬 `http://127.0.0.1:8000/personas`와 공개 `https://api-vignette.chanpaca.net/personas` 모두 비로그인 401 확인 완료.
+- 로컬 웹이 `http://127.0.0.1:5175`처럼 다른 Vite 포트로 떠도 로그인은 `로컬 테스트 계정으로 계속` 버튼을 사용한다. Google OAuth 버튼은 로컬에서는 disabled로 둔다. 현재 OAuth callback이 공개 API로 돌아가기 때문에 로컬 Google OAuth는 로컬 세션에 붙을 수 없다.
+- 중복 Vite/API/gateway/cloudflared 프로세스는 정리했다. 현재 확인용 프로세스는 `127.0.0.1:8000` dev API, `127.0.0.1:9099` engine gateway, `127.0.0.1:8001` prod public API, `cloudflared` tunnel 1개다. Playwright 전체 테스트는 자체 Vite web server를 `127.0.0.1:5173`에 띄워 검증했다.
+- 공개 런타임 재기동 스크립트:
+  - start: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-public-runtime.ps1`
+  - stop: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\stop-public-runtime.ps1`
 
-## ⚠️ 상주 인프라 (윤찬 PC, 세션 넘겨도 살아있음 — 안 끄면)
-| 프로세스 | 포트 | 재시작 |
-|---|---|---|
-| 엔진 게이트웨이 (claude -p 상주풀) | 9099 | `cd apps/api && C:/Users/encep/AppData/Local/Programs/Python/Python311/python.exe -m uvicorn engine_gateway.gateway:app --host 127.0.0.1 --port 9099` |
-| API 서버 (FastAPI) | 8000 | 아래 env로 `python -m uvicorn app.main:app --host 127.0.0.1 --port 8000` (WorkingDir apps/api) |
-| cloudflared (vignette tunnel ca8c5be0) | — | `cloudflared tunnel --config C:\Users\encep\.cloudflared\vignette-config.yml run` |
+## 이번 세션 완료
 
-API env(필수): `ENGINE_URL=http://127.0.0.1:9099` `ENGINE_MODE=claude_cli` `ENVIRONMENT=dev` `CORS_ORIGINS=["https://vignette.chanpaca.net","https://vignette-b1q.pages.dev","http://localhost:5173"]`
-- health 확인: `curl https://api-vignette.chanpaca.net/health` → 200 / `curl -X POST .../sessions -d '{"persona_code":"P1","theory_mode":"humanistic"}'` → 201
+- 남아 있던 E2E seed persona 결합을 제거했다.
+  - `session-persistence`, `teacher`, `voice` 스펙은 `/api/personas`에서 실제 DB persona를 가져와 사용한다.
+  - `voice-success`만 DB-offline fixture라 `ALLOW_SEED_PERSONA_FALLBACK=true`와 `P1`을 의도적으로 유지하고 주석을 남겼다.
+- 운영 설정 fail-closed를 강화했다.
+  - `ENVIRONMENT != dev`에서 dev login, seed fallback, 기본 session secret, OAuth 누락, localhost frontend/CORS를 설정 검증에서 거부한다.
+  - API lifespan은 DB 초기화 실패 시 dev에서만 degraded fallback을 허용하고, staging/prod에서는 시작 실패로 둔다.
+  - `SettingsConfigDict(populate_by_name=True)`를 추가해 테스트/코드에서 field name 기반 설정 생성이 가능하게 했다.
+- `infra/docker-compose.yml`을 깨끗한 ASCII compose로 재작성했다.
+  - `ENVIRONMENT`, Google OAuth client id/secret, `OAUTH_REDIRECT_URI`, `CORS_ORIGINS`, `OPENAI_BASE_URL`을 API 컨테이너에 명시 주입한다.
+  - 기존 손상된 줄 때문에 `OPENAI_API_KEY`가 주석/중복으로 처리되던 문제를 제거했다.
+  - 기본 `FRONTEND_BASE_URL`은 `https://vignette.chanpaca.net`로 수정했다.
+- `infra/.env.example`에 운영 필수 값을 보강했다.
+  - `ENVIRONMENT=prod`, `OAUTH_GOOGLE_CLIENT_ID`, `OAUTH_GOOGLE_CLIENT_SECRET`
+  - 기본 CORS에서 localhost 제거. 로컬 개발은 주석대로 `ENVIRONMENT=dev`와 localhost CORS를 별도 추가.
+- admin UI 안정화.
+  - health card의 긴 engine readiness JSON이 모바일 폭을 밀어내지 않도록 줄바꿈 처리.
+  - backend admin health는 동적인 raw JSON detail 대신 안정적인 `Engine readiness failed` 문구를 내려준다.
+  - 전역 engine config를 바꾸는 `db-persistence` E2E는 `@single-run`으로 분리했다.
+  - 사용자 생성 후 UI가 서버 목록 reload를 끝내기 전에 카드를 찾던 E2E 타이밍을 안정화했다. 생성한 이메일로 검색한 뒤 실제 서버 응답 카드만 검증한다.
+  - 사용자 관리 UI는 DB 사용자 저장소가 durable하지 않으면 생성/수정/비활성화를 막는다.
+  - AI 운영 라벨은 `Claude CLI 게이트웨이`, `Anthropic API`, `OpenAI 호환`, `Solar`처럼 실제 어댑터명으로 표시한다.
+  - 설정의 AI 운영 패널은 `/admin/health` 기반 응답 생성 상태를 함께 보여주되, health 지연이 설정 폼 로딩을 막지 않도록 분리했다.
+  - 비개발 환경에서 `admin_engine_config` singleton row가 없으면 runtime default로 내려가지 않고 fail-closed 한다.
+  - 비개발 DB 장애 상태는 `임시 기록`이 아니라 저장소 중단으로 표시한다.
+- public Google OAuth smoke 문서를 보강했다.
+  - `E2E_PUBLIC_AUTH=1`에서는 로컬 Vite 서버를 띄우지 않고 공개 웹을 대상으로 한다.
+  - storageState는 인증 쿠키를 포함하므로 `node_modules/.tmp` 아래 민감 파일로 취급한다.
+  - API session TTL은 현재 8시간이다.
+- 공개 API prod 전환을 완료했다.
+  - `cloudflared` ingress를 `127.0.0.1:8000`에서 `127.0.0.1:8001`로 변경했다.
+  - `https://api-vignette.chanpaca.net/health`가 `environment:"prod"`, `db:true`, `engine:true`를 반환한다.
+  - public production-safe Playwright 게이트가 통과한다.
+- 공개 런타임 start/stop 스크립트를 추가했다.
+  - `scripts/start-public-runtime.ps1`는 prod-safe env override로 API 8001을 띄우고 health를 검증한다.
+  - 기본 실행 시 `cloudflared`도 vignette config 기준으로 재시작한다.
+  - `scripts/stop-public-runtime.ps1`는 8001 API를 정리한다. `-StopCloudflared`를 붙이면 터널도 같이 정리한다.
+- 공개 API 보안 경계를 보강했다.
+  - `apps/api/app/routes/personas.py`에 `CurrentPrincipal`을 붙여 persona catalog를 authenticated-only로 전환했다.
+  - 로컬 E2E `auth.spec.ts`에 비로그인 `/api/personas => 401` 회귀를 추가했다.
+  - public readiness gate는 빈 API request context로 비로그인 `/personas => 401`을 확인한다. storageState가 붙은 request fixture를 쓰지 않도록 처리했다.
+- 공개 웹 API base fallback을 보강했다.
+  - `apps/web/src/lib/api.ts`는 `VITE_API_BASE`가 없고 host가 `vignette.chanpaca.net` 또는 `*.pages.dev`이면 `https://api-vignette.chanpaca.net`을 기본 API origin으로 사용한다.
+  - 이 변경으로 public web의 `/api/auth/config`가 SPA HTML로 떨어져 Google 버튼이 disabled 되는 문제를 피한다.
+- 로컬 로그인 UX를 보강했다.
+  - `apps/web/src/pages/Login.tsx`는 로컬 origin에서 OAuth redirect URI가 공개 API이면 Google 버튼을 disabled 처리하고 `로컬 테스트 계정으로 로그인` 안내를 보여준다.
+  - `auth.spec.ts`에 로컬 테스트 계정 로그인 후 `/learn` redirect 회귀를 추가했다.
+- 학습자 홈 기록 UX를 보강했다.
+  - `apps/web/src/pages/LearnerHome.tsx`는 세션이 0개인 사용자에게도 실제 서버 세션 0개를 기반으로 `기존 회기` 빈 상태와 0 카운트를 보여준다.
+  - 기록이 있을 때만 `has-session-records` 압축 레이아웃을 쓰도록 분리했다. 0회 사용자 모바일에서도 선택 내담자 정보, 새 회기 CTA, 기록 빈 상태가 문서 스크롤 없이 보인다.
+  - `apps/web/e2e/readiness.spec.ts`는 fake 12회/최근 8회 부재뿐 아니라 서버 기반 0회 빈 상태를 기대하도록 갱신했다.
+  - history의 반복 CTA는 `다시 시도` 대신 `다시 연습`으로 바꿔 기록 회고와 새 회기 시작 의미를 분리했다.
+- 직접 세션 URL의 persona 우회 경로를 막았다.
+  - `LearnerHome`에서만 막던 `degraded` 또는 non-DB persona 차단을 `Session` 직접 진입 경로에도 적용했다.
+  - `/learn/session/:personaCode`로 직접 들어와도 DB 원본 persona가 아니면 `회기 시작` 버튼이 비활성화된다.
+  - desktop/mobile E2E에 degraded `seed_fallback` persona route mock 회귀를 추가했다.
+- active session dense viewport를 보정했다.
+  - `apps/web/src/pages/session/session.css`에서 380px 이하/낮은 화면의 stage padding과 avatar 크기를 줄여 stage 내부 clipping을 없앴다.
+  - `session-layout.spec.ts` dense viewport desktop/mobile 회귀와 전체 Playwright에서 확인했다.
+- active session 텍스트 턴 저장/표시 흐름을 실제 SSE 계약에 맞췄다.
+  - 프론트 `sessionApi.stream`은 실제 백엔드 계약인 `POST /sessions/{id}/stream`을 fetch stream으로 소비한다.
+  - `/stream` 요청이 거절되거나 SSE가 열린 뒤 error 이벤트로 끝나면 학습자 발화와 부분 내담자 응답을 transcript에 남기지 않고 입력값을 복원한다.
+  - 내담자 자막은 로컬 typewriter가 아니라 서버 token 이벤트로만 쌓는다.
+  - 백엔드 `/turn`과 `/stream`은 엔진 성공 전 learner turn/state를 append하지 않도록 순서를 바꿨고, `app.test_session_turn_persistence` 회귀로 검증했다.
+- 음성 회기 실패 턴 저장/표시도 같은 기준으로 맞췄다.
+  - voice route는 엔진 응답 생성 성공 후에만 learner/client turn을 저장한다.
+  - 프론트는 음성 transcript를 pending으로 표시하고, 엔진 실패 시 pending transcript를 제거한다.
+  - 음성 degraded reason의 내부 `seed_fallback`/runtime store 표현은 사용자용 한국어 상태 문구로 바꿨다.
+- admin health의 dev DB fallback 문구를 `임시 기록`이 아니라 `비영구 런타임 기록`으로 정리했다.
+- Live2D demo fallback을 제거했다.
+  - Mao/Haru 샘플 모델은 로컬 통합 확인용 자산으로만 남기고 모든 페르소나의 공용 fallback으로 쓰지 않는다.
+  - `AvatarPersona.live2dModelUrl`이 명시된 실제 페르소나 모델이 있을 때만 Live2D를 렌더링하며, 없거나 실패하면 SVG persona avatar를 유지한다.
 
-## ✅ 완료 (대시보드 구현·인프라)
-- 프론트 7화면(로그인/학습자홈/세션/리뷰/교수자/관리자/설정) 공개배포 + 라이트테마
-- 백엔드 풀 라이브: 게이트웨이(/v1/generate·/v1/stream 어댑터) + API(orchestrator: 가드레일→상태머신→페르소나→엔진→평가) + **DB 없이 degraded(store 인메모리 폴백)**
-- named tunnel + CORS + puppeteer 실화면 검증(서연 실응답)
-- 커스텀도메인 vignette.chanpaca.net **SSL active**
-- DB 마이그레이션 35테이블+pgvector (검증 후 Docker 내림. 운영 DB는 NAS PostgreSQL 설계)
-- 합성 골든셋 62발화(P4-P7 비위기, `data/golden/`+`data/personas/`) + 평가AI few-shot 연결(`evaluator.py` GOLDEN_DIR)
+## 검증 결과
 
-## 🔴 다음 세션이 이어받을 작업 (윤찬 최신 지시 2건)
-### 1. 학습자홈 목업 제거 (최우선) — `apps/web/src/pages/LearnerHome.tsx`
-윤찬: "신규 사용자인데 **12회 연습/수련님/이미 있는 회기 목록**이 가짜로 차있으면 안 돼. 애당초 목업이 없어야."
-- 빼야 할 mock: `MOCK_WEEK`(doneCount/reviewPending/weeklyGoal), `MOCK_SESSIONS`(회기 목록), `MOCK_GROWTH`(성장 추세), `MOCK_NEXT`(추천), 253줄 `"지금까지 12회 연습했어요"`, `MOCK_LEARNER_NAME_FALLBACK`("도윤"/"수련님")
-- 목표: 신규 사용자 **빈 상태(empty state)** — 0회, 빈 회기, "아직 연습 기록이 없어요 → 첫 상담 연습을 시작해보세요" CTA 중심. 또는 API(`GET /sessions` 류)에서 실제 사용자 데이터 로드(없으면 빈).
-- 주의: "연습 시작" 라우팅은 이미 고침(navigate(`/learn/session/:personaCode`)) — 빈 상태에서도 CTA는 살려야.
+- Web typecheck:
+  - `cd apps/web; fnm env --use-on-cd | Out-String | Invoke-Expression; fnm use 22.22.3; npm run typecheck`
+  - Passed
+- Backend unit/compile:
+  - `cd apps/api; C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe -m unittest app.test_runtime_policy app.test_session_turn_persistence engine_gateway.test_gateway_model`
+  - `20 tests OK`
+  - `python -m compileall app engine_gateway`
+  - Passed
+- Web production build:
+  - `cd apps/web; fnm use 22.22.3; npm run build`
+  - Passed
+- Docker compose config:
+  - `cd infra`
+  - With dummy required env vars, `docker compose --env-file .env.example config --quiet`
+  - Passed
+- Focused Playwright after fixes:
+  - `npx playwright test e2e/admin.spec.ts e2e/db-persistence.spec.ts e2e/voice-success.spec.ts --project=chromium-desktop --project=chromium-mobile --project=chromium-single-run`
+  - `10 passed`
+- Admin manage-users focused rerun:
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/admin.spec.ts --project=chromium-desktop --project=chromium-mobile --grep "manage real server-known users"`
+  - `2 passed`
+- Full Playwright:
+  - `cd apps/web; PLAYWRIGHT_HOST=127.0.0.1 npx playwright test`
+  - `72 passed` after public API/cloudflared was restored
+  - 참고: tunnel을 내린 직후 첫 전체 실행은 public login gate 2개만 `Cloudflare 1033`으로 실패하고 나머지 `70 passed`였다. `scripts\start-public-runtime.ps1`로 prod public API와 cloudflared를 복구한 뒤 전체 재실행에서 `72 passed`.
+- Public auth project discovery:
+  - `E2E_PUBLIC_AUTH=1 npx playwright test --list --project=chromium-public-auth`
+  - `2 tests`: public production-safe config + real OAuth `/turn`
+- Public production-safe gate:
+  - `E2E_PUBLIC_AUTH=1 npx playwright test e2e/public-auth-turn.spec.ts --project=chromium-public-auth --grep "production-safe"`
+  - `1 passed` on rerun
+- Admin/settings focused E2E:
+  - `npx playwright test e2e/admin.spec.ts e2e/settings.spec.ts --project=chromium-desktop --project=chromium-mobile --project=chromium-single-run`
+  - Latest focused reruns: `admin.spec.ts` `8 passed`, `settings.spec.ts` `9 passed`
+- Auth/readiness focused E2E:
+  - `npx playwright test e2e/auth.spec.ts e2e/readiness.spec.ts --project=chromium-desktop --project=chromium-mobile`
+  - `14 passed`
+- Persona auth boundary:
+  - local unauth `http://127.0.0.1:8000/personas` -> 401
+  - public unauth `https://api-vignette.chanpaca.net/personas` -> 401
+- Public runtime script:
+  - `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-public-runtime.ps1`
+  - API 8001 health and public `https://api-vignette.chanpaca.net/health` both returned `environment:"prod"`, `db:true`, `engine:true`
+- Public login screen:
+  - `npx playwright test e2e/auth.spec.ts --project=chromium-desktop --grep "public login"`
+  - `1 passed`
+- Local login on `127.0.0.1:5175`:
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/auth.spec.ts --project=chromium-desktop`
+  - `6 passed`
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/auth.spec.ts --project=chromium-mobile`
+  - `6 passed`
+  - focused local dev-login redirect: `1 passed`
+- Learner home/history focused verification:
+  - `cd apps/web; npm run typecheck`
+  - Passed
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/learner.spec.ts e2e/readiness.spec.ts --project=chromium-desktop --project=chromium-mobile`
+  - `14 passed`
+  - Visual audit screenshots: `apps/web/node_modules/.tmp/ui-audit/learn-empty-desktop.png`, `apps/web/node_modules/.tmp/ui-audit/learn-empty-mobile-compact.png`
+  - Screenshot metrics confirmed desktop/mobile document overflow `x:0, y:0`, empty history visible, and real stats area present.
+- Session dense viewport verification:
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/session-layout.spec.ts --project=chromium-desktop --project=chromium-mobile`
+  - `8 passed`
+- Latest voice/session focused E2E:
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/voice.spec.ts e2e/voice-success.spec.ts e2e/session-layout.spec.ts --project=chromium-desktop --project=chromium-mobile --project=chromium-single-run`
+  - `15 passed`
+- Latest learner/session/settings/admin focused E2E:
+  - `PLAYWRIGHT_BASE_URL=http://127.0.0.1:5175 PLAYWRIGHT_SKIP_WEB_SERVER=1 npx playwright test e2e/learner.spec.ts e2e/session-layout.spec.ts e2e/settings.spec.ts e2e/admin.spec.ts --project=chromium-desktop --project=chromium-mobile --project=chromium-single-run`
+  - `37 passed`
 
-### 2. 음성 입력 — `services/voice.py` + `routes/voice.py`(WSS) + `Session.tsx` 마이크
-윤찬: "크롬으로 하니까 내 음성이 안 들어감. 브라우저 어떻게 해야하는지 해야함."
-- (a) 크롬 **마이크 권한** — HTTPS(vignette.chanpaca.net)는 OK, getUserMedia 권한 요청 UI 필요
-- (b) **음성 파이프라인 실연동** — STT(OpenAI whisper) → orchestrator turn → TTS. WSS `/api/voice/ws`(Caddyfile passthrough 있음). Session.tsx 마이크 버튼이 현재 UI만 — WSS 연동 필요.
-- ⚠️ **OpenAI 키 필요**: 현재 `.env`/API env의 `OPENAI_API_KEY`가 dummy. 윤찬에게 실키 받아야 STT/TTS 동작. 키 없으면 services/voice.py가 degraded(501/503).
+## 아직 못 끝낸 것
 
-## 외부 블로커 (자율 불가)
-- **n=1 실 임상 축어록**: 한신대 교수 회신 필요. 요청 메일초안 = `Projects/영업/2026/한신대학교 산학협력 프로젝트/축어록_추가요청_메일초안.md` (윤찬 발송 대기). 합성 데이터로 개발 단계는 완화함.
+- 공개 Google OAuth 실제 `/turn` proof는 아직 없다.
+  - 이유: `E2E_PUBLIC_STORAGE_STATE=apps/web/node_modules/.tmp/public-auth.json`가 아직 확보되지 않았다.
+  - 사용자가 Playwright codegen 브라우저에서 Google 로그인 후 storageState를 저장해야 한다.
+  - 2026-06-26 14:43 KST 기준 `apps/web/node_modules/.tmp/public-auth.json`은 없다. codegen 창/프로세스가 남아 있으면 로그인 완료 후 창을 닫아 저장을 완료하면 된다.
+- 공개 API `environment:"dev"` 문제는 이번 세션에서 해결했다. cloudflared가 prod API인 `127.0.0.1:8001`을 보도록 변경했고 public gate로 확인했다.
+- Google Console 설정은 브라우저 로그인 세션이 필요하다. 막히면 사용자가 로그인해 주기로 했다.
+- worktree는 원래부터 매우 dirty이고, 이전 세션/사용자 변경이 많다. 관련 없는 변경을 되돌리지 말 것.
 
-## 핵심 함정/패턴 (꼭 지킬 것)
-- **빌드는 반드시 node22** — node23.4.0은 vite **segfault**(출력 0줄). PowerShell: `fnm env --use-on-cd | Out-String | Invoke-Expression; fnm use 22.22.3`
-- 프론트 빌드: `$env:VITE_API_BASE="https://api-vignette.chanpaca.net"; npm run build`
-- 배포: `wrangler pages deploy dist --project-name vignette --branch main --commit-dirty=true` (먼저 `dist/_redirects`에 `/*  /index.html  200`)
-- **deployment 미리보기 URL은 CORS 불일치** → 검증은 production(vignette.chanpaca.net) URL로
-- 라이브 검증 도구: `apps/web/_pptr_flow.cjs` (puppeteer-core + 시스템 Chrome, mock auth 주입 후 풀흐름 클릭) — `node _pptr_flow.cjs "https://vignette.chanpaca.net" <out.png>`
-- dev 인증 우회: `ENVIRONMENT=dev`면 쿠키 없어도 통과(deps.py). 프론트 mock auth = localStorage `vignette.dev-auth`
-- 한글 JSON은 **python httpx로** 보낼 것(curl -d 한글 인코딩 깨짐)
-- Cloudflare 토큰: wrangler oauth(`%APPDATA%\xdg.config\.wrangler\config\default.toml`) / DNS 권한은 cloudflared `cert.pem`의 ARGO TOKEN apiToken
+## 다음 세션 우선순위
 
-## 윤찬 작업방식 (위반 주의)
-- **완료보고 불신** — 실화면 인터랙션(puppeteer 클릭)까지 검증 후 보고. CORS/API 200만으론 "완료" 금지.
-- **목업 싫어함** — 가짜 데이터로 화면 채우지 말 것. 빈 상태/실데이터.
-- **디코로 답변 필수** — chat_id 1485472826118115338, inbound는 reply로.
-- 위험은 한 번 알리고 주저말고 진행(확인 반복 금지). 단 Docker 같은 명시 가드는 존중.
+1. Google OAuth Console을 확인한다.
+   - Authorized redirect URI: `https://api-vignette.chanpaca.net/auth/callback`
+   - Authorized JavaScript origin: `https://vignette.chanpaca.net`
+   - 앱/도메인 설정은 `hs.ac.kr`, `twentyoz.kr` 계정만 서버 claim 검증으로 허용한다. Google Console의 authorized domains와 이메일 도메인 제한은 다른 개념이다.
+2. storageState를 캡처하고 public `/turn` smoke를 실행한다.
+   - `cd D:\workspace\vignette\apps\web`
+   - `npx playwright codegen https://vignette.chanpaca.net/login --save-storage=.\node_modules\.tmp\public-auth.json`
+   - `$env:E2E_PUBLIC_AUTH="1"`
+   - `$env:E2E_PUBLIC_STORAGE_STATE=".\node_modules\.tmp\public-auth.json"`
+   - `.\node_modules\.bin\playwright.cmd test e2e/public-auth-turn.spec.ts --project=chromium-public-auth`
+3. UI/UX는 계속 `docs/DESIGN_CONCEPT.md`를 따른다.
+   - learner home은 빈 사용자에게 fake 통계/기록을 보여주지 않는다. 0회 상태는 실제 서버 기록 0개로 `기존 회기` 빈 상태를 보여주는 현재 구현을 유지한다.
+   - active learning session은 전체 화면, 문서 스크롤 없음이 원칙이다.
+   - 실제 session history는 `기존 회기`, `이어하기`, `기록/리뷰`, `다시 연습`, `새 회기 시작` 흐름으로 유지한다.
+4. 다음 배포 전 `admin/engine-config`를 다시 확인한다.
+   - 의도된 현재값이 `claude_cli / http://127.0.0.1:9099 / gateway-default`인지 확인.
+   - E2E가 engine config를 건드리므로 배포 전 실제 운영값을 반드시 재확인한다.
+
+## 로컬 실행 명령
+
+Engine gateway:
+
+```powershell
+cd D:\workspace\vignette\apps\api
+C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe -m uvicorn engine_gateway.gateway:app --host 127.0.0.1 --port 9099
+```
+
+API:
+
+```powershell
+cd D:\workspace\vignette\apps\api
+$env:ENGINE_URL="http://127.0.0.1:9099"
+$env:ENGINE_MODE="claude_cli"
+$env:ENVIRONMENT="dev"
+$env:AUTH_DEV_LOGIN_ENABLED="true"
+C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000
+```
+
+Public API process:
+
+```powershell
+cd D:\workspace\vignette
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-public-runtime.ps1
+```
+
+Web:
+
+```powershell
+cd D:\workspace\vignette\apps\web
+fnm env --use-on-cd | Out-String | Invoke-Expression
+fnm use 22.22.3
+npm run dev -- --host localhost --port 5173
+```
+
+## 최근 주요 변경 파일
+
+- `apps/web/e2e/support.ts`
+- `apps/web/e2e/auth.spec.ts`
+- `apps/web/e2e/learner.spec.ts`
+- `apps/web/e2e/session-layout.spec.ts`
+- `apps/web/e2e/session-review.spec.ts`
+- `apps/web/e2e/session-persistence.spec.ts`
+- `apps/web/e2e/teacher.spec.ts`
+- `apps/web/e2e/voice.spec.ts`
+- `apps/web/e2e/voice-success.spec.ts`
+- `apps/web/e2e/public-auth-turn.spec.ts`
+- `apps/web/e2e/db-persistence.spec.ts`
+- `apps/web/e2e/README.md`
+- `apps/web/playwright.config.ts`
+- `apps/web/src/pages/Admin.tsx`
+- `apps/web/src/pages/Login.tsx`
+- `apps/web/src/pages/Session.tsx`
+- `apps/web/src/pages/Settings.tsx`
+- `apps/web/src/pages/session/session.css`
+- `apps/web/src/components/avatar/ClientAvatar.tsx`
+- `apps/web/src/components/avatar/persona.ts`
+- `apps/web/public/live2d/README.md`
+- `apps/api/app/config.py`
+- `apps/api/app/main.py`
+- `apps/api/app/routes/admin.py`
+- `apps/api/app/routes/personas.py`
+- `apps/api/app/routes/users.py`
+- `apps/api/app/routes/voice.py`
+- `apps/api/app/test_session_turn_persistence.py`
+- `apps/api/app/test_runtime_policy.py`
+- `infra/docker-compose.yml`
+- `infra/.env.example`
+- `docs/HANDOFF.md`
+- `docs/dev_dashboard.html`
+- `apps/web/src/lib/api.ts`