diff --git a/README.md b/README.md
index 3ee6994..e4f2f01 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,9 @@ Slack 기반 AI 어시스턴트 **로빙(Robeing)** 프로젝트의 모든 문
 - [ngrok 테스트 가이드](./docs/setups/ngrok-test-guide.md)
 - [이메일 설정 가이드](./docs/setups/Email_readme.md) - Gmail API 실시간 수신 및 발송 완전 가이드
 
+### 트러블슈팅
+- [troubleshooting](./docs/troubleshooting/) - 문제 해결 가이드 모음
+
 ### 외부 참조
 - [Slack API 문서](https://api.slack.com/web)
 - [OpenAI API 문서](https://platform.openai.com/docs)
diff --git a/docs/20250714_migration_from_github.md b/docs/20250714_migration_from_github.md
new file mode 100644
index 0000000..f79bb32
--- /dev/null
+++ b/docs/20250714_migration_from_github.md
@@ -0,0 +1,121 @@
+# GitHub → Gitea 마이그레이션 가이드
+
+**날짜**: 2025-07-14  
+**작업자**: Claude (RO-BEING 시스템 관리)
+
+## 개요
+
+ivada-Robeing 조직의 모든 GitHub 저장소를 자체 호스팅 Gitea 서버로 마이그레이션한 작업 기록입니다.
+
+## 마이그레이션 대상 저장소
+
+총 7개 저장소가 성공적으로 이전되었습니다:
+
+| GitHub 저장소 | Gitea 저장소 | 크기 | 설명 |
+|---------------|--------------|------|------|
+| `ivada-Robeing/DOCS.git` | `ivada_Ro-being/docs.git` | 548KB | 프로젝트 문서 |
+| `ivada-Robeing/frontend-base.git` | `ivada_Ro-being/frontend-base.git` | 7.8MB | React 대시보드 |
+| `ivada-Robeing/api-base.git` | `ivada_Ro-being/api-base.git` | 616KB | 안정화 API |
+| `ivada-Robeing/test.git` | `ivada_Ro-being/test.git` | 3.1MB | 메인 백엔드 (뇌) |
+| `ivada-Robeing/test_meta-skill.git` | `ivada_Ro-being/test-meta-skill.git` | 220KB | 스킬 실험실 |
+| `ivada-Robeing/test_front.git` | `ivada_Ro-being/test-front.git` | 6.6MB | 프론트 통합 테스트 |
+| `ivada-Robeing/nginx-infra.git` | `ivada_Ro-being/nginx-infra.git` | 256KB | Nginx 인프라 설정 |
+
+**총 데이터량**: 약 19MB
+
+## 발생한 문제
+
+### HTTP 413 오류 (Request Entity Too Large)
+
+**증상**: 2MB 이상의 파일(이미지 등)이 포함된 저장소 push 시 413 오류 발생
+
+**원인**: nginx의 기본 `client_max_body_size` 제한 (1MB)
+
+**해결책**:
+```bash
+# nginx 설정 파일 수정
+sudo nano /etc/nginx/sites-available/default
+
+# git.ro-being.com 서버 블록에 추가
+server {
+    listen 443 ssl http2;
+    server_name git.ro-being.com;
+    
+    client_max_body_size 100M;  # 추가된 설정
+    
+    # ... 기타 설정
+}
+
+# 설정 테스트 및 적용
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+## 마이그레이션 절차
+
+### 1. GitHub 저장소 클론
+```bash
+mkdir -p github-migration && cd github-migration
+
+# GitHub 토큰 사용하여 클론
+git clone https://TOKEN@github.com/ivada-Robeing/REPO_NAME.git
+```
+
+### 2. Gitea 저장소 생성
+웹 인터페이스에서 각 저장소 생성:
+- https://git.ro-being.com
+
+### 3. Remote URL 변경 및 Push
+```bash
+cd REPO_NAME
+
+# remote URL을 Gitea로 변경
+git remote set-url origin https://USERNAME:TOKEN@git.ro-being.com/ivada_Ro-being/REPO_NAME.git
+
+# 메인 브랜치 push
+git push -u origin main
+
+# 충돌 시 force push (기존 내용 덮어쓰기)
+git push -f origin main
+```
+
+## 사용된 인증 정보
+
+- **GitHub Token**: `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`
+- **Gitea Token**: `b18d3b01a802f001f3e2649cbd750008710a1d99`
+- **Gitea 사용자**: `ivada_Ro-being`
+
+## 후속 작업
+
+### 완료된 작업
+- [x] 모든 저장소 마이그레이션 완료
+- [x] nginx 파일 크기 제한 해제
+- [x] 마이그레이션 문서 작성
+
+### 권장 사항
+1. **GitHub 저장소 아카이브**: 원본 저장소를 read-only로 설정
+2. **로컬 환경 업데이트**: 개발자들의 로컬 remote URL 변경
+3. **CI/CD 파이프라인 업데이트**: GitHub Actions → Gitea Actions 마이그레이션
+4. **Webhook 설정**: Slack 알림 등 기존 통합 기능 재설정
+
+## 트러블슈팅
+
+### 일반적인 문제들
+
+**문제**: `error: RPC 실패; HTTP 413`
+**해결**: nginx `client_max_body_size` 증가
+
+**문제**: `! [rejected] main -> main (fetch first)`
+**해결**: `git push -f origin main` 으로 강제 푸시
+
+**문제**: 큰 파일 (100MB+) 업로드 실패
+**해결**: Git LFS 설정 필요
+
+## 참고 링크
+
+- **Gitea 서버**: https://git.ro-being.com
+- **백업 정책**: `/home/admin/BACKUP_TO_NAS_POLICY.md`
+- **아키텍처 문서**: `/home/admin/ROBING_ARCHITECTURE_PHILOSOPHY.md`
+
+---
+*이 문서는 Claude에 의해 자동 생성되었습니다.*
\ No newline at end of file