create-saas-starter-workspace 0.1.0

package/templates/workspace/.claude/skills/store-release-guide/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: store-release-guide
+description: 스토어 출시 정책·콘솔·심사. 개발자 계정(Apple $99·Google $25) 가입·Apple 4.2/4.2.2 심사 통과 전략·소셜 로그인 OAuth 콘솔 셋업·Play 비공개(closed) 테스트 12명·14일 게이트·TestFlight 테스터 관리·App Store "Submit for Review"·App Privacy/데이터 안전 라벨·계정 삭제 컴플라이언스 작업 시 자동 로드됩니다. (EAS 빌드·제출 명령·OTA는 eas-deploy-guide.)
+user-invocable: false
+---
+
+# 스토어 셋업·출시 가이드 (출시 준비 + 소셜 로그인 fast-follow)
+
+> 이 문서는 현재 템플릿에서 무엇이 들어가고 무엇이 fast-follow인지 정직하게 구분한다.
+> 앱 출시는 AI가 단계별로 안내한다. 단, 돈·신원·2FA가 걸린 일은 Owner가 직접 한다.
+
+## 누가 무엇을 하나 (가역성 분류)
+
+| 표시 | 의미 | 예 |
+|---|---|---|
+| 🟢 | AI / CLI 자동 | EAS 빌드·제출, 인증서 파일 작업, 설정 파일 |
+| 🟡 | Owner가 대시보드에서 (AI가 정확히 안내) | 첫 Apple 로그인+2FA, 스크린샷, App Privacy 라벨, Play SA JSON |
+| 🔴 | Owner가 직접 (대리 불가) | 카드 결제, 신원 검증, 멤버십 가입 |
+
+---
+
+## 1. 개발자 계정 (🔴 Owner — 유료·환불 불가, 가장 먼저)
+
+| | Apple Developer Program | Google Play Console |
+|---|---|---|
+| 비용 | **$99 / 년** (갱신형, 환불 불가) | **$25** (1회, 환불 불가) |
+| 계정 유형 | Individual 권장 (D-U-N-S 회피, 신원 검증만) | Personal 권장 |
+| 판매자명 | 개인 법적 이름이 **공개 판매자명**이 된다 (프라이버시 1줄 confirm) | 동일 |
+| 리드타임 함정 | 신원 검증 수 시간~2일 | **신규 개인계정은 production 전 비공개(closed) 테스트 12명·14일 연속 강제** (내부 테스트는 카운트 X·조직계정 면제) |
+
+> 지배적 지연은 Apple 신원 검증이 아니라 Google의 12명·14일 게이트다 ([Play Console 정책](https://support.google.com/googleplay/android-developer/answer/14151465)).
+> production 출시까지 최소 2주가 막혀 있다. 그래서 **Google Play Console 가입을 가장 먼저** 해 두라.
+> Apple도 $99 결제 후 멤버십 활성화에 시간이 걸릴 수 있다. 둘 다 코드 작업 전에 시작하라.
+
+이 둘은 AI가 대신 가입하지 못한다 (카드·신원·2FA). AI는 가입 화면과 입력값을 안내한다.
+
+---
+
+## 2. Apple Guideline 4.2 — 웹뷰 래퍼 심사 통과 (가장 중요)
+
+웹사이트를 그대로 비추는 얇은 웹뷰는 4.2.2(웹 클리핑·애그리게이터) 정석 거절 사유다 ([App Review Guidelines §4.2](https://developer.apple.com/app-store/review/guidelines/)). 2026 기준 실측으로 4.2 / 4.2.2 거절이 웹뷰 앱의 1순위 사유다.
+통과의 핵심은 폰이기 때문에 가능한 진짜 네이티브 차별 요소가 하나라도 있어야 한다는 것이다.
+
+### 셸이 실제로 채우는 것 (정직하게)
+
+셸은 화면을 만들지 않는다. 웹뷰가 막거나 없는 네이티브 빈틈만 메운다. 그래서 확실히 네이티브 전용인 표면은 오프라인 화면뿐이고, 로딩·에러·로그인은 웹과 겹치거나 웹의 것이다.
+
+| 요소 | v1 상태 | 설명 |
+|---|---|---|
+| 오프라인 화면 | ✅ v1 (유일한 네이티브 전용 표면) | NetInfo로 라이브 연결 끊김 감지 → 네이티브 오프라인 화면 + 다시 시도. 네트워크가 없으면 웹은 아예 못 뜨므로 웹에 대응물이 없다 |
+| 로딩·에러 오버레이 | ✅ v1 (첫/하드 로드 + 크래시 한정) | 첫 로드(빈 웹뷰)와 크래시 재마운트 때만 네이티브가 보여준다. 인앱(SPA) 화면 전환과 인페이지/데이터 오류는 웹이 자기 UI로 처리한다 (네이티브는 SPA 내비를 못 본다) |
+| Android 하드웨어 뒤로가기 | ✅ v1 | 웹뷰 history 우선, 없으면 OS 위임 |
+| 외부 링크 네이티브 처리 | ✅ v1 | 외부 origin·`mailto:`·`tel:`은 시스템 브라우저/앱으로 (아웃바운드) |
+| safe-area(노치) 여백 | ✅ v1 | 네이티브가 측정한 inset을 CSS 변수로 웹에 주입 |
+| 카메라·마이크·파일 업로드 권한 연결 | ✅ v1 (enablement) | 기능 자체는 웹(`getUserMedia`)·라이브러리(`<input type=file>` 피커)의 것. 셸은 동작하도록 권한 배선만 더한다 (§3·아래) |
+| 푸시 알림 | ❌ v1 부재 | 4.2를 위해 권장하는 네이티브 차별 요소. v1엔 들어 있지 않고(앱 의존성·기능 없음), 요청 시 AI가 구현한다 |
+| 생체인증 (Face ID 등) | ❌ v1 부재 | 진짜 네이티브 전용. v1 이후 |
+| 네이티브 소셜 로그인 (Google·Apple 원클릭) | ❌ v1 부재 | onPress 없는 disabled 버튼만 존재(Apple은 iOS 한정). 켜려면 OAuth 클라이언트 ID 발급(§3) + 네이티브 SDK→idToken→`requestSessionHandoff` 배선이 필요하다. "준비 중" 라벨은 자동 활성화가 아니라 미구현 표시다 |
+
+> 카메라·마이크·파일 업로드는 셸이 구현한 기능이 아니다. https + 권한 문자열·`mediaCapturePermissionGrantType=grant`·Android CAMERA로 웹의 기능이 동작하게 해주는 enablement다.
+
+### 4.2 제출 전 체크리스트
+
+- [ ] 오프라인에서 빈 흰 화면이 아니라 **네이티브 오프라인 화면**이 뜨는가 (실기기에서 비행기 모드로 확인)
+- [ ] 첫 로드 중 빈 화면이 아니라 **로딩 인디케이터**가 뜨는가 (첫/하드 로드 한정; SPA 전환은 웹이 처리)
+- [ ] 첫 로드 실패/크래시 시 **에러 화면 + 다시 시도**(통째 재마운트)가 있는가
+- [ ] 외부 링크가 앱 안에 갇히지 않고 시스템 브라우저로 열리는가
+- [ ] **네이티브 차별 요소를 하나 이상** 더했는가 (권장: 푸시) — 안 하면 4.2 위험이 높다
+- [ ] (소셜 로그인을 켰다면) **Sign in with Apple**이 동등하게 있는가 (§3, 없으면 4.8 거절 — 소셜을 안 켰으면 면제)
+- [ ] **배포된 웹**에 (웹뷰에서 도달 가능한) **계정 삭제** 경로가 있는가 (웹뷰 렌더 = 인앱 인정; 5.1.1(v), §6)
+- [ ] 켜지 않은 권한이 `Info.plist`/매니페스트에 남아 있지 않은가 (미사용 권한 = 거절 사유)
+- [ ] (푸시를 더했다면) 그게 **네이티브 차별 요소**로 리뷰 노트에 설명돼 있는가
+
+---
+
+## 3. 소셜 로그인 (🟡 fast-follow — v1은 비활성 scaffold)
+
+로그인은 웹의 것이다. 기본적으로 앱은 로그인에 아무것도 하지 않는다. 웹의 로그인 UI(이메일/비밀번호 포함)가 웹뷰 안에서 그대로 뜨고, 쿠키·JS·스토리지가 켜져 있어 `@supabase/ssr`이 그대로 동작한다.
+
+- 네이티브 로그인 모달은 opt-in scaffold다. 웹이 `REQUEST_SESSION_INSTALL`을 보낼 때만 뜨고, 유일하게 활성인 "이메일로 계속하기" 버튼은 인증 없이 모달을 닫아 웹 로그인으로 되돌려보낼 뿐이다(리로드·내비게이션 없음).
+- 네이티브 소셜 버튼(Google·Apple 원클릭)은 비활성 "준비 중" 스텁이다 (`login.socialComingSoon`, `onPress` 없음; Apple 버튼은 iOS에서만 표시). 켜는 건 fast-follow이고 콘솔 셋업이 따라온다.
+
+### 왜 소셜은 네이티브여야 하나 (in-webview OAuth는 동작하지 않는다)
+
+> 임베디드 웹뷰 안에서는 소셜 OAuth가 작동하지 않는다. Google은 임베디드 웹뷰의 OAuth를 차단하고([`disallowed_useragent`, 2021/2023 시행](https://developers.googleblog.com/upcoming-security-changes-to-googles-oauth-20-authorization-endpoint-in-embedded-webviews/)), [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252)는 임베디드 user-agent를 금지한다.
+> 그래서 소셜 로그인은 반드시 **네이티브**(시스템 브라우저 / 네이티브 credential picker)여야 한다.
+
+### 규칙: 소셜을 쓰면 Sign in with Apple 강제 (Apple 4.8 — 조건부)
+
+> 4.8은 조건부다. Google이나 다른 서드파티 소셜 로그인을 (주 계정용으로) 하나라도 켜면, iOS에서는 "Sign in with Apple"을 동등하게 넣어야 한다.
+> 웹이 Supabase 이메일/비밀번호만 쓰면 4.8은 적용되지 않는다.
+> 소셜을 켤 경우, 이건 구조적 불변식이자 백엔드(Supabase Apple provider) 실배선까지 진단 대상이다. "Google만 켜고 Apple은 나중에"는 **불가능**하다(둘은 같이 켜진다).
+
+### Google OAuth 클라이언트 ID (3종)
+
+Google은 플랫폼마다 OAuth 클라이언트가 필요하다. 코드에는 **webClientId(Web 타입)만** 넣는다.
+
+| 클라이언트 | 어디서 | 용도 |
+|---|---|---|
+| Web | Google Cloud Console → Credentials | 코드의 `webClientId` (idToken audience) |
+| iOS | 동일 | iOS 네이티브 로그인 |
+| Android | 동일 | Android 네이티브 로그인 |
+
+함정:
+- iOS reversed URL scheme은 플러그인에 수동으로 붙여넣는다 (자동 계산 아님). 누락 시 iOS 소셜 로그인 무한 로딩.
+- SHA-1 지문은 모든 서명 키를 등록한다. Play 앱 서명 키 + EAS 업로드 키(internal/dev 빌드 키 포함). 일부만 등록하면 `DEVELOPER_ERROR`.
+- Google SA(서비스 계정)는 Cloud Console(생성+API Enable)과 Play Console(SA 초대·권한) 두 콘솔을 거친다 (노출까지 ~24h 지연).
+
+### Apple Sign In
+
+게이트로 두 방식 중 하나를 고른다:
+
+| 방식 | 필요한 것 | 권장 |
+|---|---|---|
+| **네이티브 idToken** (기본) | bundle ID만 | ✅ — Services ID 회피 |
+| 웹 OAuth | Apple Services ID + `.p8` 키 + 6개월마다 시크릿 갱신 | 피한다 |
+
+> **한국 개발자 (2026-01-01~)**: Apple Services ID 등록/갱신 시 server-to-server 엔드포인트가 필수가 됐다 ([Apple 공지](https://developer.apple.com/news/?id=j9zukcr6)).
+> 이건 웹 OAuth 방식에만 해당한다. 기본인 네이티브 idToken 방식을 쓰면 Services ID 자체가 없어 이 요구를 회피한다.
+> 그래서 한국 Owner에게는 네이티브 idToken 방식을 강력 권장한다.
+
+핸드오프 함수(`requestSessionHandoff`)는 구현·테스트됐으나 호출자가 없다. 켜려면 입력인 네이티브 idToken 획득도 미배선이고, 출력을 받는 웹 라우트(POST `/auth/app-bridge` + nonce consume)는 이 앱이 아니라 `docs/web-adapter`에서 웹 repo에 설치해야 한다. `secureSession` get/set도 v1 호출자 없음. 기본 로그인은 웹의 것이다. 실제 켜기·콘솔 셋업은 fast-follow이며 이 문서가 단계별 절차를 담는다(전용 출시 스킬은 v1 이후).
+
+---
+
+## 4. EAS Build + Submit 흐름 (🟢 대부분 자동)
+
+EAS가 서명을 관리한다. Owner가 fastlane을 직접 구성할 일은 없다. `eas build`/`eas submit`이 빌드 + 테스트 채널(TestFlight / Play Internal) 업로드까지 해주고, 나머지(스토어 리스팅·스크린샷·App Privacy·"Submit for Review"·Play production 승급·SA JSON)는 GUI/수동이다.
+
+```bash
+# 1) 빌드 (클라우드) — production 빌드 하나로 테스트와 출시를 모두 충당
+npx eas-cli build --profile production --platform all          # iOS IPA + Android AAB
+
+# 2) 제출 (스토어 테스트 채널까지 — 공개 심사는 아님, §5)
+npx eas-cli submit --profile production --platform ios         # → TestFlight
+npx eas-cli submit --profile production --platform android     # → Play 내부 테스트 트랙
+```
+
+> 첫 제출은 두 스토어가 다르다:
+> - **iOS** — EAS가 ASC 앱 레코드를 (없으면) 자동 생성한다 → 첫 `eas submit -p ios`가 그대로 TestFlight까지 간다 ([Expo Submit iOS](https://docs.expo.dev/submit/ios/)).
+> - **Android** — Google Play API는 첫 릴리스를 만들지 못한다. Owner가 Play Console에서 앱을 만들고 첫 AAB를 수동 업로드해야(아무 트랙이나) 하며, 그 다음부터 `eas submit -p android`가 동작한다 ([Expo: first Android submission](https://github.com/expo/fyi/blob/main/first-android-submission.md)).
+
+### EAS가 자동 생성·관리하는 것 (🟢 — .cer/.jks 손 안 댐)
+
+- iOS: 배포 인증서, 프로비저닝 프로파일, APNs 키(푸시용)
+- Android: 업로드 키스토어
+- iOS 제출용 ASC API 키: EAS 자동 생성 (Account Holder가 1회 'Request Access' 약관 동의 선행) — 권장. (`eas.json`엔 대안인 `appleId` 방식 placeholder도 있으나 둘 중 하나만.)
+
+### 수동인 것 (🟡)
+
+- **Play 서비스 계정 JSON** (Android 제출 인증): 한 번만 만든다. `eas.json`엔 경로를 넣지 않는다(시크릿 커밋 위험). 첫 `eas submit -p android`가 JSON 경로를 물으면 그때 주고, EAS가 서버에 저장한다(`$ENV` 보간 미지원). 만드는 순서 ([Expo 절차](https://github.com/expo/fyi/blob/main/creating-google-service-account.md)):
+  1. Cloud Console → **Google Play Android Developer API**(`androidpublisher.googleapis.com`) **Enable**
+  2. IAM & Admin → **서비스 계정 생성** (역할 지정은 skip)
+  3. 그 계정 → 키 → **JSON 키 생성·다운로드** (시크릿, 커밋 금지)
+  4. Play Console → **사용자 및 권한** → 그 SA 이메일 **초대** + 앱/계정 권한 부여 (권한 반영 지연 가능)
+- **Android FCM v1 서비스 계정**(푸시용): Firebase Console에서 수동 생성 → EAS 업로드.
+
+> `eas.json`엔 public 값만 커밋한다. 시크릿은 EAS 서버에 둔다.
+> `google-services.json`(public·커밋) ↔ FCM SA JSON(시크릿) ↔ Play 제출 SA JSON. 셋은 별개다. 혼동하지 말라.
+
+### EAS 무료 티어 (선고지)
+
+- iOS 15회 + Android 15회 / 월 · 동시성 1 · Low 우선순위 · 빌드당 ~45분 ([Expo 요금](https://expo.dev/pricing))
+- 첫 빌드는 10–20분 + 큐 대기다. 멈춘 게 아니다.
+- JS 변경은 빌드 풀을 소모하지 않지만(OTA), 초기 네이티브 셋업엔 iOS 빌드 수 개를 소모할 수 있다.
+
+---
+
+## 5. TestFlight / Play Internal → 공개 출시 (🔴 트랩)
+
+> `eas submit`은 공개 심사 제출을 하지 않는다.
+> iOS는 TestFlight까지, Android는 internal 트랙까지만 올린다.
+
+공개 출시는 🟡 수동 + 명시적 confirm이다:
+
+| 플랫폼 | 테스트 채널 (eas submit 도달점) | 공개 출시 (수동) |
+|---|---|---|
+| iOS | TestFlight | App Store Connect에서 **"Submit for Review"** |
+| Android | Internal 트랙 | **비공개(closed) 테스트 12명·14일 통과 후** production 승급 |
+
+- 내부(internal) 테스트는 12·14 게이트에 카운트되지 않는다. `eas submit`이 올리는 내부 트랙은 Owner 본인 확인용이고, production 전엔 비공개(closed) 트랙에 테스터 12명·14일 연속을 따로 채워야 한다(구글이 14일간 테스터 실사용 시간까지 측정). 조직(D-U-N-S) 계정은 이 게이트를 면제받는다.
+- Android 첫 AAB는 Play Console에 수동으로 1회 업로드해야 한다 (Play API는 첫 릴리스를 못 만든다. 첫 자동 제출 실패는 정상이니 선고지하라).
+- 초기 확인도 production 빌드를 TestFlight·Play 내부 테스트로 보내 실기기에서 한다. 별도 preview/ad-hoc 빌드를 만들지 않는다(같은 빌드를 그대로 출시로 승급 → EAS 빌드 수 절약). 빠른 사이드로드가 꼭 필요하면 `distribution: "internal"` 프로파일을 따로 추가할 수 있다.
+
+---
+
+## 6. 컴플라이언스 (🟡 수동)
+
+- **계정 삭제 (5.1.1(v))** ([Apple 가이드](https://developer.apple.com/support/offering-account-deletion-in-your-app/)): 인앱 삭제 경로가 필수다 (비활성화로는 불충분). 이 셸은 계정 UI를 웹에 위임하므로,
+  배포된 웹에 삭제 화면이 있어야 한다. 웹뷰 안에서 도달 가능하면 "인앱"으로 인정된다. 네이티브 소셜 포함
+  모든 로그인에서 도달 가능해야 하고, 서버에서 `auth.admin.deleteUser` (server-only)로 실제 삭제한다.
+- **세 프라이버시 산출물** — App Privacy(iOS 라벨) · Data Safety(Android) · `PrivacyInfo.xcprivacy` — 는 taxonomy가 달라
+  복붙이 안 된다. 단일 데이터 인벤토리에서 각각 매핑한다.
+- **ATT**: 기본 No (Supabase·Sentry는 비추적). 단 웹뷰가 로드하는 웹의 트래커(GA4·Pixel 등)는 개발자 책임이다 →
+  배포된 웹의 스크립트를 실점검하라.
+- 스크린샷 · 연령등급(IARC) = 🟡 수동.
+
+---
+
+## 한눈 요약: v1 vs fast-follow
+
+| | v1 (지금 들어감) | fast-follow (v1 부재, 켜는 절차는 위에) |
+|---|---|---|
+| 셸이 채우는 것 | 오프라인 화면 + (첫/하드 로드·크래시 한정) 로딩·에러 + 뒤로가기 + 외부 링크 + safe-area + 카메라·파일 권한 연결 | — |
+| 로그인 | **웹의 것** (웹 로그인 UI가 웹뷰 안에서 그대로). 네이티브 모달은 opt-in scaffold, 소셜 버튼은 비활성 "준비 중" 스텁 | 네이티브 Google/Apple 원클릭 (소셜 켜면 Sign in with Apple 동반) |
+| 푸시 | 부재 (forward-compat 메시지 타입만) | AI가 요청 시 구현 (4.2용 권장 네이티브 차별 요소) |
+| 생체인증 | 부재 | v1 이후 |
+| 출시 | EAS Build/Submit 흐름 문서화 | 첫 공개 심사 제출 (§5 절차로 안내) |
+
+---
+
+## 출처 (Sources)
+
+외부 정책·동작 주장의 권위 있는 출처. (앱 자체 동작은 코드·다른 가이드가 SSOT다.)
+
+**Apple**
+
+- [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/) — 4.2(최소 기능)·4.8(Sign in with Apple)·5.1.1(v)(계정 삭제)
+- [계정 삭제 요건 가이드](https://developer.apple.com/support/offering-account-deletion-in-your-app/) — 5.1.1(v)
+- [Sign in with Apple — 한국 server-to-server 요건(2026-01-01~)](https://developer.apple.com/news/?id=j9zukcr6) · [S2S 알림 설정 help](https://developer.apple.com/help/account/configure-app-capabilities/enabling-server-to-server-notifications/)
+- [Apple Developer Program](https://developer.apple.com/programs/)
+
+**Google Play**
+
+- [신규 개인계정 테스트 요건 — closed 12명·14일](https://support.google.com/googleplay/android-developer/answer/14151465)
+- [테스트 트랙 설정 — internal·closed·open](https://support.google.com/googleplay/android-developer/answer/9845334)
+
+**Expo / EAS**
+
+- [EAS Submit 개요](https://docs.expo.dev/submit/introduction/) · [iOS](https://docs.expo.dev/submit/ios/) · [Android](https://docs.expo.dev/submit/android/)
+- [첫 Android 제출은 수동 업로드 필요](https://github.com/expo/fyi/blob/main/first-android-submission.md)
+- [Play 서비스 계정 JSON 만들기](https://github.com/expo/fyi/blob/main/creating-google-service-account.md) · [ASC API 키 만들기](https://github.com/expo/fyi/blob/main/creating-asc-api-key.md)
+- [eas.json 설정](https://docs.expo.dev/eas/json/) · [내부 배포(internal distribution)](https://docs.expo.dev/build/internal-distribution/) · [EAS Build용 Apple Developer 역할](https://docs.expo.dev/app-signing/apple-developer-program-roles-and-permissions/)
+- [요금·무료 티어 한도](https://expo.dev/pricing) · [플랜](https://docs.expo.dev/billing/plans/)
+
+**OAuth / 보안**
+
+- [Google: 임베디드 웹뷰 OAuth 차단 공지(`disallowed_useragent`)](https://developers.googleblog.com/upcoming-security-changes-to-googles-oauth-20-authorization-endpoint-in-embedded-webviews/)
+- [RFC 8252 — OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)

package/templates/workspace/.claude/skills/vercel-cron/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: vercel-cron
+description: Rules for adding Vercel Cron jobs in this template. Use when adding scheduled tasks or periodic jobs.
+user-invocable: false
+---
+
+# vercel-cron
+
+Vercel Cron 추가 시 분기·로그·테스트 함정을 짚는다.
+
+주기나 부하가 Hobby 한도와 부딪힐 것 같으면 Owner에게 먼저 알린다.
+
+- **prod에서만 실행한다.** `env.APP_ENV !== "production"`이면 no-op으로 둔다. preview에서 dev DB와 외부 API를 낭비하는 일을 막는다.
+- 성공과 실패를 모두 logger로 기록한다. 성공은 `audit`, 실패는 `error`로 남긴다. Sentry와 logs 송출은 자동으로 이뤄진다.
+- 테스트 함정: `env`는 모듈 로드 시 한 번만 parse하므로 `vi.stubEnv`가 듣지 않는다. `vi.mock("@/lib/env.server")`로 통째 교체한다.
+
+그 외(헤더 검증·idempotent·`CRON_SECRET`·`vercel.json`·`env.server.ts` 등)는 Vercel docs와 코드 주석을 따른다.

package/templates/workspace/.claude/skills/warmup/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: warmup
+description: Verify the AI agent's tools and environment (CLI installs, logins) and install/audit dependencies in web/ (and mobile/ when present), fixing issues where possible. Use when the Owner runs /warmup, just opened the workspace, or before tasks that depend on external CLIs working.
+---
+
+# /warmup
+
+AI(CLI agent)가 이 워크스페이스에서 작업할 준비가 됐는지 점검한다.
+도구·자격·환경과 프로젝트의 실행 환경을 정상화한다.
+
+스스로 바로잡을 수 있는 것은 자율로 설정한다.
+Owner의 행동이 필요한 부분은 AskUserQuestion으로 해결한다.
+
+## CLI
+
+- `node` — 현 LTS
+- `pnpm` — latest (워크스페이스는 pnpm 기준 · 각 repo `package.json`의 `packageManager`로 버전 고정)
+- `git`
+- `gh` — 로그인
+- `vercel` — 로그인
+- `pnpm exec supabase` — 로그인 (CLI는 `web/` devDependency로 고정되어 있다 — `web/`에서 실행. `npx supabase`로 별도 사본을 받지 않는다)
+- `sentry-cli` — 로그인
+
+앱(`mobile/`)까지 갈 때 필요한 `eas-cli` 로그인은 첫 빌드 시점에 `/preview`가 안내한다. 여기서는 점검하지 않는다.
+
+## 의존성
+
+워크스페이스 루트의 `package.json`은 `pnpm doctor`(환경 점검) 진입점만 가진다 — 루트에 의존성을 설치하지 않는다. `web/`과 `mobile/`은 각자 독립 프로젝트이므로 의존성도 각자 설치한다.
+
+- `web/`에서 `pnpm install` 후 `pnpm audit`.
+- `mobile/`이 있으면(앱 단계 이후) `mobile/`에서도 동일하게 한다.
+
+세부 정책은 각 repo의 `.npmrc`와 CI 설정을 따른다. 보안 게이트(cooldown, audit level 등)는 우회하거나 수정하지 않는다.

package/templates/workspace/AGENTS.md

@@ -0,0 +1,39 @@
+# saas-starter-workspace
+
+서비스들 위의 컨텍스트 레이어. 이 repo의 git은 공유 맥락(에이전트 도구·계약·문서)만 추적한다. `web/`와 `mobile/`은 각자 자기 git·배포를 가진 독립 repo다.
+
+사람용 시작 안내는 `START-HERE.md`. 이 파일은 에이전트의 운영 컨텍스트다.
+
+## 구성
+
+- `web/` — 웹 SaaS (Next.js + Supabase). 자기 git → GitHub → Vercel로 배포한다. 화면·기능·데이터의 본체이자 SSOT.
+- `mobile/` — 배포된 web을 WebView로 감싸는 네이티브 셸 (Expo). 자기 git → EAS → 스토어로 배포한다. 웹뷰가 못 메우는 네이티브 공백(푸시·홈 화면 아이콘·오프라인 화면)만 채운다.
+- `ssb/` — web ↔ mobile postMessage 계약의 SSOT. `web/lib/bridge/`와 `mobile/src/bridge/`에 바이트 단위로 동일하게 복사된다.
+- `.claude/` — 에이전트 도구(스킬·설정). 워크스페이스 루트에만 둔다.
+- `scripts/doctor.mjs` — 환경·로그인 점검(`pnpm doctor`). 진단과 안내까지만 하고 자동 수리는 하지 않는다. Owner가 ✗ 해결을 부탁하면 doctor의 → 안내를 따라 수행하고 다시 doctor로 검증한다.
+- `workspace.json` — 생성기가 기록한 메타(프로젝트명·선택한 코딩 에이전트). doctor가 읽는다.
+
+## 불변식
+
+- 각 서비스는 독립 repo다. 서로 import하지 않고, 공유는 복사된 계약(`ssb/`)으로만 한다.
+- web은 단독으로 완결된다. mobile은 그 위에 얹는 선택적 레이어이고, web은 mobile에 의존하지 않는다.
+- 클라우드 프로비저닝·git·배포 명령은 해당 서비스 폴더 안에서 실행한다. `/go-live`는 `web/`에서(web이 배포 단위), 앱 빌드·출시는 `mobile/`에서. 워크스페이스 루트를 한 repo로 묶거나 `web/`·`mobile/`을 부모 git에 add하지 않는다.
+- 에이전트 도구(스킬·`.claude/` 설정)는 워크스페이스 루트에만 둔다. `web/`·`mobile/`은 도구가 없는 순수 코드이고, 각자 자기 `AGENTS.md`(그 repo를 직접 손보는 사람용)만 둔다.
+- 한 서비스에만 속한 지식은 그 서비스 repo가 진다. 서비스를 가로지르는 맥락만 여기가 진다.
+
+## 이 템플릿의 성격
+
+빈 골격이다. `web/features/`와 `web/supabase/migrations/`는 비어 있고, 로그인·글·피드 같은 제품 기능은 사용자 주제에 맞춰 대화로 만든다. 인프라(데이터 접근 seam, RLS 기본 활성화, 환경 분리, 로깅·테스트, 디자인 시스템, 코드 컨벤션)는 갖춰져 있다.
+
+기능 제작은 `web/AGENTS.md`의 규약을 따른다(FSD-light, `features/<f>/repository.ts` 데이터 접근 seam, RLS 동봉, schema 3층). 앱 작업은 `mobile/AGENTS.md`와 자동 로드되는 가이드 스킬(`native-app-guide`·`bridge-guide`·`eas-deploy-guide`·`store-release-guide`)을 따른다.
+
+## 운영 원칙
+
+- 복잡성을 먼저 의심한다. 기본값은 추가하지 않는 것이다. 파일·폴더·추상화는 지금 자격이 있을 때만 만든다.
+- 한 파일·폴더는 하나의 책임만 진다. 범용 버킷(`docs/`·`misc/` 같은)은 만들지 않는다.
+- 의도는 배치로 드러낸다. 처음 본 사람이 "이게 왜 여기 있지"를 묻지 않도록, 이름이 곧 관심사가 되게 한다.
+- 간결하게 쓴다. 근거는 커밋 메시지에 남기고, 본문은 약어 나열이 아니라 완전한 문장으로 쓴다.
+- 비개발자 owner라도 best practice를 깎지 않는다.
+- 점진 확장은 사용자가 직접 한다. 추측으로 미리 만들지 않는다.
+- 지식 배치: 작업 시 자동으로 떠야 하는 지식은 스킬(트리거 = `description`), 매 세션 참인 사실은 이 파일과 각 repo의 `AGENTS.md`, 작정하고 보는 레퍼런스는 `docs/`.
+- 언어: 한국어로 소통하고, 코드 식별자·기술 용어는 원문을 유지한다. 커밋은 Conventional Commits(영어).

package/templates/workspace/CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- AGENTS.md를 그대로 불러옵니다. 에이전트 규칙은 AGENTS.md에서 단일 관리합니다(중복 사본을 두지 않음). -->
+@AGENTS.md

package/templates/workspace/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 시스템설계자
+
+This template is distributed to students of the author's course
+(brand: 시스템설계자).
+
+You may use it as the starting point for any of your own projects —
+personal or commercial. You may modify it freely, ship products built
+with it, and you keep all rights to the work you create on top.
+
+You may not redistribute the template itself, repackage it as a course
+or book, or include it in any dataset used to train machine learning
+models. Access is part of the course.
+
+THE TEMPLATE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED. THE AUTHOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE TEMPLATE OR ITS
+USE.

package/templates/workspace/README.md

@@ -0,0 +1,20 @@
+# saas-starter-workspace
+
+웹 SaaS를 만들고, 원하면 그대로 스토어 앱으로 감싸는 스타터입니다. 화면·코드·배포는 AI 코딩 에이전트가 맡고, 당신은 무엇을 만들지 정합니다.
+
+처음이라면 [START-HERE.md](START-HERE.md)부터 여세요. 설치, 명령 순서, 폴더 구조가 거기 있습니다.
+
+## 구성
+
+```
+(프로젝트 폴더)/   에이전트를 여는 단일 진입점
+├── web/      웹 SaaS (Next.js · Supabase · Vercel). 화면·기능·데이터의 본체.
+├── mobile/   그 웹을 감싸는 스토어 앱 (Expo · EAS).
+├── ssb/      web ↔ mobile 통신 계약. 손댈 일은 거의 없습니다.
+├── scripts/  환경 점검 도구(`pnpm doctor`).
+└── .claude/  에이전트 도구(스킬·설정).
+```
+
+`web/`과 `mobile/`은 각자 배포되는 독립 프로젝트입니다. 이 워크스페이스는 둘을 잇는 공유 맥락(에이전트 도구·계약)만 둡니다. 에이전트 운영 규칙은 [AGENTS.md](AGENTS.md)에 있습니다.
+
+수강생에게 배포되는 강의용 템플릿입니다. [LICENSE](LICENSE).

package/templates/workspace/START-HERE.md

@@ -0,0 +1,52 @@
+# 여기서 시작하세요
+
+나만의 웹 서비스를 만들고, 그것을 스토어 앱으로 감싸 운영하기 위한 출발점입니다. 화면·코드·배포는 AI 코딩 에이전트가 맡고, 당신은 무엇을 만들지 결정합니다.
+
+## 1. 준비 (한 번만)
+
+이 폴더는 강의의 설치 명령(한 줄)이 만들었습니다. 그 명령이 필요한 도구 설치와 로그인까지 안내했으니, 남은 준비는 하나입니다:
+
+1. 터미널에서 이 폴더로 이동해 코딩 에이전트를 엽니다 — 기본은 Claude Code(`claude` 입력), Codex·OpenCode도 동작합니다. 안쪽의 `web/`·`mobile/`이 아니라 루트에서 엽니다. 명령(스킬)은 여기에 있습니다.
+2. 처음 열면 에이전트가 로그인(구독 계정)을 안내합니다. 한 번만 하면 됩니다.
+3. 그다음부터는 아래 명령을 입력하거나, 평소 말로 부탁하면 됩니다.
+
+> 환경이 멀쩡한지 궁금할 땐 언제든 터미널에서 `pnpm doctor`를 실행하세요. 도구·로그인 상태를 ✓/✗로 보여주고, ✗마다 해결 방법을 알려줍니다.
+
+## 2. 명령 순서
+
+위에서 아래로, 한 번에 하나씩. 명령은 `/`로 시작합니다.
+
+| 명령 | 무엇을 하나 | 당신이 하는 일 |
+| --- | --- | --- |
+| `/warmup` | 도구·로그인 점검, 의존성 설치 | 부족한 로그인만 따라 하기 |
+| `/go-live` | GitHub·Vercel·Supabase·Sentry를 만들고 `web/`을 실제 주소로 첫 배포 | 비가역 작업만 확인 |
+| `/probe <아이디어>` | 만들 서비스를 인터뷰로 구체화 | 질문에 답하기 |
+| `/sketch` | 화면 디자인 시안 보여주기 | 마음에 드는 안 고르기 |
+| "OO 기능 만들어줘" | 로그인·글쓰기·피드·승인 등 기능을 대화로 제작 | 원하는 바 말하기 |
+| `git push` (AI가 실행) | 자동 재배포 → 즉시 라이브 | 주소 확인 |
+| `/kickoff` | 배포된 웹을 앱(`mobile/`)으로 감싸기, 1회 셋업 | 비용 확인 후 진행 |
+| `/preview` | 앱을 폰에 설치해 보기(TestFlight·Play 내부 테스트) | 폰에서 확인 |
+| `/launch` · `/release` | 스토어 첫 출시 · 이후 업데이트 | 콘솔에서 공개 버튼 |
+
+`/go-live`로 빈 서비스를 먼저 띄우고, 그 위에 기능을 하나씩 얹어 `git push`로 계속 배포합니다. 웹에 올린 변화는 앱에도 재심사 없이 그대로 반영됩니다.
+
+## 3. 이 안에 뭐가 있나
+
+```
+(내 프로젝트 폴더)/   지금 이 폴더. 코딩 에이전트를 여기서 엽니다.
+├── web/      당신의 웹 서비스 (Next.js → Vercel). 모든 화면·기능·데이터의 본체.
+├── mobile/   그 웹을 감싸는 스토어 앱 (Expo → 앱·플레이스토어). 푸시·홈 화면 아이콘처럼 앱만의 것.
+├── ssb/      web ↔ mobile이 주고받는 통신 계약. 손대지 않아도 됩니다.
+├── scripts/  환경 점검 도구(`pnpm doctor`).
+└── .claude/  위 명령(스킬)이 있는 곳.
+```
+
+본체는 `web/`입니다. 거의 모든 작업이 웹에서 일어나고, `mobile/`은 그 웹을 띄우는 얇은 껍데기(셸)입니다. 둘은 각자 독립된 프로젝트라 따로 배포됩니다(웹은 Vercel, 앱은 스토어).
+
+## 4. 알아둘 것
+
+- 이건 빈 골격입니다. 로그인·글·피드 같은 기능은 미리 들어 있지 않고, 당신 주제에 맞게 AI와 함께 만듭니다. 프로젝트 이름은 생성할 때 입력한 이름이 코드 전체에 들어가 있고, 바꾸고 싶으면 AI에게 부탁하면 됩니다.
+- 돈·신원이 걸린 일은 AI가 대신 못 합니다. 카드 결제, 로그인 2FA, 스토어 콘솔의 공개 버튼은 당신이 직접 누르고, AI가 그 순간을 짚어 줍니다.
+- 앱 스토어는 일찍 시작하세요. Apple Developer는 연 $99, Google Play는 1회 $25입니다(둘 다 환불 불가). 특히 신규 Google 계정은 정식 공개 전에 "비공개 테스트 12명·14일 연속"을 통과해야 해서 출시까지 2주 이상 걸릴 수 있습니다. 앱까지 갈 계획이면 코드 작업과 별개로 가장 먼저 계정을 만들어 두세요.
+
+막히면 Claude Code에게 물어보세요. 이 폴더의 도구와 문서를 안 채로 답합니다.

package/templates/workspace/gitignore

@@ -0,0 +1,18 @@
+# OS / 로컬 산출물
+.DS_Store
+*.log
+
+# 중첩 서비스(web/·mobile/)는 각자 자기 git을 가진 독립 repo다.
+# 워크스페이스 루트는 공유 맥락 레이어만 추적한다(web/·mobile/은 여기서 추적하지 않는다).
+/*
+!/.gitignore
+!/README.md
+!/START-HERE.md
+!/AGENTS.md
+!/CLAUDE.md
+!/LICENSE
+!/.claude/
+!/ssb/
+!/package.json
+!/scripts/
+!/workspace.json

package/templates/workspace/mobile/.env.example

@@ -0,0 +1,25 @@
+# .env.example — 이 파일을 복사해 `.env`로 저장한 뒤 값을 채우세요.
+#   cp .env.example .env
+# .env 는 .gitignore 로 커밋에서 제외됩니다. .env.example(이 파일)은 커밋합니다.
+#
+# EXPO_PUBLIC_* 접두사가 붙은 값만 앱 번들에 인라인됩니다(빌드 시점 고정 — 값을 바꾸면 재빌드 필요).
+# 비밀(토큰·시크릿)은 절대 EXPO_PUBLIC_* 로 넣지 마세요. 앱 코드는 src/config/env.ts 통해서만 읽습니다.
+
+# 앱이 띄울 실서비스 웹 주소. 항상 배포된 prod 웹(https)을 가리킵니다.
+# (실기기는 localhost에 못 닿고 http는 카메라·로그인 쿠키가 조용히 깨집니다 → 반드시 https.)
+EXPO_PUBLIC_WEB_URL=http://localhost:3000
+
+# 스토어/홈 화면에 표시될 앱 이름.
+EXPO_PUBLIC_APP_NAME=My App
+
+# iOS 번들 식별자 (Apple Developer 등록값과 동일, 역도메인 형식).
+EXPO_PUBLIC_IOS_BUNDLE_ID=com.example.myapp
+
+# Android 패키지명 (Play Console 등록값과 동일, 역도메인 형식).
+EXPO_PUBLIC_ANDROID_PACKAGE=com.example.myapp
+
+# 딥링크 scheme (소문자, 공백 없음). 로그인 리다이렉트 등에 myapp:// 형태로 쓰입니다.
+EXPO_PUBLIC_SCHEME=myapp
+
+# EAS 프로젝트 ID. `eas init` 후 발급됩니다. 로컬에서는 비워둬도 빌드 시 EAS가 채웁니다.
+EXPO_PUBLIC_EAS_PROJECT_ID=

package/templates/workspace/mobile/AGENTS.md

@@ -0,0 +1,69 @@
+# my-space-app
+
+배포된 prod 웹을 https로 WebView에 띄우는 얇은 셸이다(React Native + Expo). 모든 화면·기능·로그인은 웹(Next.js)의 것이고, 셸은 화면을 만들지 않는다. 웹뷰가 막거나 못 하는 네이티브 공백만 메운다: 오프라인 화면, 첫 로드와 크래시 재마운트 한정의 로딩·에러 오버레이, Android 하드웨어 뒤로가기, 외부 링크의 시스템 브라우저 라우팅, safe-area inset 주입, 카메라·마이크·파일 업로드 권한 배선. SSOT는 언제나 웹이다.
+
+> Owner는 원하는 것을 말하고("앱 이름 정해줘", "미리보기 보여줘"), AI가 CLI·코드·빌드를 맡는다.
+
+## Expo: SDK 56 / RN 0.85 / React 19 — 작성 전 확인
+
+코드를 쓰기 전 v56 문서(<https://docs.expo.dev/versions/v56.0.0/>)나 설치된 타입(`node_modules/<pkg>/`)을 읽는다. SDK 56·RN 0.85·React 19는 API·이벤트 구독·edge-to-edge 기본값이 학습 데이터와 다르다. 메모리를 믿지 않는다.
+
+## 폴더 구조 (FSD-light)
+
+```
+App.tsx                 # 진입점 — 슬라이스 조합만, 로직 없음 (FIXED)
+index.ts                # URL polyfill + registerRootComponent (FIXED)
+app.config.ts           # Expo 설정(이름·번들ID·스킴·플러그인)
+eas.json                # EAS 빌드·제출 프로파일(dev·production)
+src/
+  config/env.ts         # EXPO_PUBLIC_WEB_URL 가드·WEB_ORIGIN·ALLOWED_ORIGINS (FIXED)
+  i18n.ts               # 네이티브 문자열만(t·getLocale), 그 외는 웹 카피 (FIXED)
+  bridge/               # 앱↔웹 계약. contract.ts·reader.ts는 SSOT (FIXED)
+  webview/              # WebView 호스트 + 셸 레시피(로딩·에러·오프라인·뒤로가기·링크·safe-area·크래시 복구)
+  session/              # 세션 핸드오프 (opt-in, v1 미사용)
+  auth/                 # 네이티브 로그인 모달 (opt-in 스캐폴드, 소셜은 비활성 stub)
+  ui/                   # 셸 전용 프리미티브(로딩·에러·오프라인 화면 등)
+docs/web-adapter/       # 웹 측 브릿지 어댑터(/kickoff이 웹 repo에 설치)
+```
+에이전트 스킬은 이 repo에 두지 않는다. 워크스페이스 루트 `.claude/`에만 둔다.
+
+- `App.tsx`는 얇다: 슬라이스를 조합만 하고 비즈니스 로직을 두지 않는다.
+- 의존은 단방향이다: `App → src/{webview,session,auth} → src/{bridge,config,ui}`. 슬라이스끼리는 공개 표면만 쓴다.
+
+## 불변식
+
+어기면 빌드·심사·보안이 깨진다. 상세는 가이드 스킬에 있고, 여기엔 규칙만 둔다.
+
+1. **ssb 브릿지가 계약의 SSOT다.** `src/bridge/contract.ts`·`reader.ts`는 웹과 바이트 단위로 동일하게 동기화되고, CI checksum이 어긋남을 막는다. 계약은 추가만 허용한다(타입·옵셔널 필드만 추가, 제거·이름변경·필수화 금지). reader는 tolerant하다(모르는·깨진 메시지는 `UNKNOWN`, 예외를 던지지 않음). 토큰은 브릿지로 보내지 않는다. → `bridge-guide`
+
+2. **세션 핸드오프는 opt-in이고 v1엔 호출자가 없다.** 기본 로그인은 웹이 직접 처리하고 셸은 관여하지 않는다.
+   - 흐름: 네이티브 로그인 → POST `/auth/app-bridge` + short-TTL 1회용 nonce → Set-Cookie 303. URL에 `?token=`을 넣지 않는다(유출).
+   - 핸드오프 뒤엔 웹이 세션 갱신을 단독으로 맡는다. 네이티브는 `autoRefreshToken:false`가 필수다. refresher가 둘이면 Supabase refresh-token reuse-detection이 세션 전체를 폐기한다.
+   - 로그아웃은 웹 signOut을 거쳐 양방향으로 처리한다. → `bridge-guide`(계약) · `native-app-guide`(셸 배선)
+
+3. **`env.ts`는 fail-loud다.** `EXPO_PUBLIC_WEB_URL`이 없거나 비었거나 파싱 실패거나 https도 localhost도 아니면 시작 시 throw한다(미가드 fallback은 release 흰 화면을 부른다). 단 가드는 protocol·hostname만 본다. 실기기와 시뮬레이터를 구분하지 못하므로 localhost URL은 가드를 통과하고도 실폰에서 깨진다. `EXPO_PUBLIC_*`는 빌드 시점에 인라인되므로, URL을 바꾸면 재빌드해야 한다. → `eas-deploy-guide`
+
+4. **테스트는 production 빌드 하나를 스토어 테스트 채널로 보내는 것이다.** 미리보기와 출시 모두 같은 production 빌드를 TestFlight(iOS)·Play 내부 테스트(Android)로 보내 실폰에서 확인하고, 그 빌드를 그대로 공개로 승급한다. EAS 빌드 수를 아끼고 실제 출시 아티팩트를 검증하기 위해서다.
+   - 승급 자체는 스토어 콘솔에서 수동으로 한다(fastlane 미사용, `eas submit`은 테스트 채널까지만).
+   - Expo Go로는 뜨지 않는다(네이티브 모듈). 시뮬레이터도 가정하지 않는다.
+   - 실기기는 prod 웹을 https로 로드한다. http는 카메라·Web Crypto·Secure 쿠키가 에러 없이 동작을 멈추고, 실기기는 localhost에 닿지 못한다.
+   - localhost dev-loop은 요청 시 development 프로파일에만 배선한다(production엔 두지 않는다). → `eas-deploy-guide`
+
+5. **네이티브 코드는 추측하지 않는다.** 작성 전 v56 문서나 설치된 타입을 읽는다(상단 Expo 절 참고). 구체 레시피는 → `native-app-guide`.
+
+## 주제 → 가이드 스킬
+
+작업을 시작하면 해당 가이드가 자동 로드된다. 상세 규약은 여기 인라인하지 않는다.
+
+| 주제 | 가이드 |
+|------|--------|
+| 앱 껍데기: WebView 호스트·로딩/에러/오프라인·Android 뒤로가기·외부 링크·safe-area·파일 업로드·딥링크·크래시 복구 | `native-app-guide` |
+| 앱↔웹 메시지 계약·새 메시지 타입 추가·tolerant reader·토큰 미경유 | `bridge-guide` |
+| 환경 모델(앱 = prod 웹 래퍼)·EAS 빌드·제출·dev build·미리보기·OTA vs 재빌드·무료 티어 | `eas-deploy-guide` |
+| 스토어 출시: 개발자 계정·4.2 심사·소셜 콘솔 셋업·제출·테스트 트랙·컴플라이언스 | `store-release-guide` |
+
+## git · 커밋 · 언어
+
+- 한국어로 소통하고, 코드 식별자·기술 용어는 원문을 유지한다. 주석은 한국어·영어 모두 가능하되, 스타터 품질로 유용하게 쓴다.
+- 커밋은 Conventional Commits(영어): `feat:`·`fix:`·`docs:`·`refactor:`·`chore:`. 예: `feat: add android back handler to webview host`.
+- 사용자 문자열은 반드시 `src/i18n.ts`의 `t()`를 거친다.

package/templates/workspace/mobile/App.tsx

@@ -0,0 +1,47 @@
+import React from "react";
+import { SystemBars } from "react-native-edge-to-edge";
+import { SafeAreaProvider, initialWindowMetrics } from "react-native-safe-area-context";
+
+import { WEB_URL } from "./src/config/env";
+import { WebViewHost } from "./src/webview/Host";
+import { LoginScreen } from "./src/auth/LoginScreen";
+import { requestNativeLogout } from "./src/session/sessionHandoff";
+
+/**
+ * 앱 루트 — 얇은 통합 레이어.
+ *
+ * SafeAreaProvider(첫 프레임 flash 방지용 initialWindowMetrics) 안에서 웹뷰 셸(WebViewHost)을
+ * 띄우고, 로그인 시트(LoginScreen 스캐폴드)를 얹는다. 실제 동작·레시피는 각 모듈이 책임지고,
+ * 여기서는 브릿지 콜백만 배선한다.
+ *
+ * - 웹이 "세션 없음"을 알리면(REQUEST_SESSION_INSTALL → onNeedLogin) 로그인 시트를 띄운다.
+ *   v1은 네이티브 소셜 로그인이 fast-follow라, 시트의 주 동작은 웹 자체 이메일 로그인으로
+ *   보내는 것이다(웹이 auth UI의 주인).
+ * - 웹 로그아웃(LOGOUT → onLoggedOut) 시 네이티브 로컬 세션 사본만 정리한다(웹 쿠키는 웹이 정리).
+ */
+export default function App(): React.JSX.Element {
+  const [showLogin, setShowLogin] = React.useState(false);
+
+  const handleNeedLogin = React.useCallback((_redirectPath?: string) => {
+    setShowLogin(true);
+  }, []);
+
+  const handleLoggedOut = React.useCallback(() => {
+    // 네이티브 로컬 사본 정리(비동기, fire-and-forget). LOGOUT_DONE은 라우터가 웹에 통지한다.
+    void requestNativeLogout();
+  }, []);
+
+  return (
+    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+      {/* SDK 56는 Android edge-to-edge가 강제 기본 — SystemBars(react-native-edge-to-edge)가
+          상태바·내비바 아이콘 스타일을 한 컴포넌트로 제어한다. light 앱이라 둘 다 어두운 아이콘. */}
+      <SystemBars style="dark" />
+      <WebViewHost url={WEB_URL} onNeedLogin={handleNeedLogin} onLoggedOut={handleLoggedOut} />
+      <LoginScreen
+        visible={showLogin}
+        onClose={() => setShowLogin(false)}
+        onContinueInWebView={() => setShowLogin(false)}
+      />
+    </SafeAreaProvider>
+  );
+}

package/templates/workspace/mobile/CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- AGENTS.md를 그대로 불러옵니다. 이 repo의 에이전트 규칙은 AGENTS.md에서 단일 관리합니다. -->
+@AGENTS.md

package/templates/workspace/mobile/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 시스템설계자
+
+This template is distributed to students of the author's course
+(brand: 시스템설계자).
+
+You may use it as the starting point for any of your own projects —
+personal or commercial. You may modify it freely, ship products built
+with it, and you keep all rights to the work you create on top.
+
+You may not redistribute the template itself, repackage it as a course
+or book, or include it in any dataset used to train machine learning
+models. Access is part of the course.
+
+THE TEMPLATE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED. THE AUTHOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE TEMPLATE OR ITS
+USE.