(cd "$(git rev-parse --show-toplevel)" && git apply --3way <<'EOF' 
diff --git a/README.md b/README.md
index 79c0873ce951b1cb9b433535fe190c74467c844d..096a2678be0cdfbaefa73249e0e0c0e520d65263 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,103 @@
-# Welcome to GitHub Desktop!
+# Cambodia Coffee Trade Platform (MVP)
 
-This is your README. READMEs are where you can communicate what your project is and how to use it.
+캄보디아 생두/원두 거래를 **신뢰 기반**으로 시작하고, 이후 글로벌로 확장하기 위한
+가벼운 초기 시스템 설계 + 실행 가이드입니다.
 
-Write your name on line 6, save it, and then head back to GitHub Desktop.
+## 1) 제품 비전
+
+- **브로커(판매 가능 커피 보유자)**와 **바이어(구매자)**를 연결한다.
+- 신뢰 문제를 해결하기 위해:
+  - 실명/사업자 중심의 **기본 신원 공개**
+  - **에스크로 결제**
+  - 거래 완료 후 **리뷰/평점** 기반 노출
+- 캄보디아 커뮤니티형으로 시작하고, 지역(아프리카/남미/아시아) → 국가 단위 확장.
+
+## 2) 핵심 역할
+
+- **Buyer**: 전세계 구매자
+- **Broker**: 농부/수집상/로스터/유통상 등 판매 가능한 커피 보유자
+- **Regional Head Broker**: 대륙/권역 책임자 (아프리카, 남미, 아시아 등)
+- **Country Broker**: 국가 단위 운영/검수/분쟁 지원
+- **Admin**: 플랫폼 운영자, KYC/분쟁/정책 관리
+
+> 초기에는 캄보디아만 운영하되, 데이터 구조는 글로벌 확장 전제로 설계.
+
+## 3) 신뢰 설계 (핵심)
+
+1. **KYC 단계화**
+   - L1: 이메일/전화 인증
+   - L2: 신분증/사업자증 제출
+   - L3: 은행 계좌 + 현장 검증(선택)
+2. **에스크로 거래 강제**
+   - 주문 결제 시 에스크로 잠금
+   - 샘플/본거래 수락 기준 충족 시 정산
+3. **거래 후 리뷰**
+   - `거래 완료` 건만 리뷰 가능
+   - 리뷰 가중치: 최근성 + 거래금액 + 검증레벨
+4. **공개 프로필**
+   - 브로커 기본 정보, 원산지, 누적 거래, 클레임 비율 공개
+
+## 4) 상품/거래 상태 모델
+
+SCA 기준 필드를 포함해 브로커가 상품 등록 후 아래 상태를 거칩니다.
+
+- `DRAFT` (임시저장)
+- `SAMPLE_AVAILABLE` (샘플 가능)
+- `TESTING` (샘플 테스트 진행)
+- `NEGOTIATING` (협상 중)
+- `IN_TRANSACTION` (에스크로 결제 완료/거래 중)
+- `COMPLETED` (거래 완료)
+- `CANCELLED` (거래 취소)
+
+상태 전이는 백엔드 정책으로 제한하고, 이벤트 로그로 추적합니다.
+
+## 5) 가장 가벼운 + 확장 가능한 기술 스택
+
+### MVP (캄보디아 시작)
+
+- **Frontend**: Next.js (App Router) + Tailwind
+- **Backend API**: NestJS 또는 FastAPI (둘 중 팀 역량 우선)
+- **DB**: PostgreSQL
+- **Auth**: Supabase Auth 또는 Auth0
+- **File Storage**: S3 호환 스토리지 (샘플 리포트/인증문서)
+- **Queue/Async**: Redis + BullMQ/Celery (알림/정산 후처리)
+- **Search**: PostgreSQL Full-Text (초기), 추후 OpenSearch
+
+### 확장 단계
+
+- 결제/에스크로를 Provider Adapter로 추상화
+- 리뷰 랭킹/추천을 별도 서비스로 분리
+- 지역/국가 운영 기능 RBAC 고도화
+
+## 6) 최소 기능(MVP) 우선순위
+
+1. 회원가입/로그인 + 역할(바이어/브로커)
+2. 브로커 KYC 제출/승인
+3. 커피 상품 등록(SCA 필드 포함)
+4. 샘플 요청 → 테스트 → 본거래 요청
+5. 에스크로 결제 상태 연동
+6. 거래 완료 후 리뷰
+7. 메인 페이지 랭킹 노출(리뷰 점수/완료건 기반)
+8. 운영자 대시보드(승인/분쟁/취소)
+
+## 7) 리포지토리 구성
+
+- `docs/architecture.md`: 아키텍처/확장 전략
+- `db/schema.sql`: MVP 데이터베이스 스키마
+- `api/openapi.yaml`: 핵심 API 명세 초안
+
+## 8) 다음 실행 단계
+
+1. `db/schema.sql` 기준으로 개발 DB 생성
+2. `api/openapi.yaml` 기반 백엔드 스캐폴드 생성
+3. Buyer/Broker 인증 + 상품등록 + 거래흐름 1차 구현
+4. 에스크로 Provider 1개 연결(국가/법규 적합 서비스)
+5. 캄보디아 파일럿(10~30개 브로커) 운영
+
+---
+
+자세한 설계는 아래 문서를 참고하세요.
+
+- [Architecture](docs/architecture.md)
+- [DB Schema](db/schema.sql)
+- [OpenAPI](api/openapi.yaml)
 
EOF
)