docs: README 동기화 섹션 Cut E 반영 — 양방향 sync + ConflictModal + Silent risk + Troubleshoot

README.md

@@ -190,37 +190,58 @@ inkling.md         원본 제품 브리프 v1.4
 
 ---
 
-## 원격 백업 (선택, F6-L2)
+## 동기화 (Git, F21 Cut E)
 
-Inkling 데이터를 사적 git 원격에 백업하려면 한 번만 설정하면 된다. 인코딩된 형식이 아니라 평문 마크다운(F5 export 형식)으로 저장되니, **반드시 비공개 repo** 를 사용한다.
+Inkling 데이터를 사적 git 원격으로 양방향 동기화 (Mac ↔ Windows 등). 평문 마크다운(F5 export 형식)으로 저장되니 **반드시 비공개 repo** 를 사용한다.
+
+상세 도움말은 앱 내 설정 → 동기화 저장소 → "도움말" 버튼 (4 섹션 modal) 참조. 본 섹션은 setup + 주요 시나리오 요약.
 
 ### 일회 설정
 
-```bash
-# 1. 빈 사적 repo 생성 (예: gitea, GitHub private)
+1. 빈 사적 repo 생성 (Gitea / GitHub private)
+2. 앱 → 설정 → 동기화 저장소 → URL 입력 → "저장"
+3. "연결 테스트" 클릭해 인증 / 네트워크 확인
+4. 자동 sync 사용 토글 + interval (기본 30분) 확인
 
-# 2. 데이터 디렉터리에 git 초기화 + 원격 등록
-cd "%APPDATA%\Inkling\Inkling\profiles\default\sync"   # Windows
-git init
-git remote add origin https://your-host/owner/inkling-data.git
-git fetch origin || true   # 빈 repo 면 무시
+URL 형식 (둘 중 하나):
 
-# 3. 자격증명 설정 (Windows Credential Manager 자동 / 또는 token 임베드 URL)
+- SSH: `git@host:user/repo.git`
+- HTTPS: `https://host/user/repo.git`
 
-# 4. 첫 동기화: 트레이 → "지금 동기화"
-```
+`git@https://...` 같은 혼합 형식은 거부된다.
 
-처음 sync 시 SyncService 가 `<profileDir>/sync/` 안에 F5 export 트리(notes/, media/, index.jsonl, manifest.json)를 덮어쓰고 `git add -A && git commit && git push -u origin <branch>` 를 자동 수행.
+### 일상 사용
 
-### 사용
+- 자동 sync: 설정한 interval 마다 + 앱 종료 시 1회
+- 수동 sync: 트레이 → "지금 동기화"
+- 충돌 발생 시 트레이 토스트 + 설정 페이지의 "충돌 해결…" 버튼 → ConflictModal
 
-- 트레이 → "지금 동기화" 로 수동 트리거
-- 앱 종료 시 자동 1회 (sync dir 이 설정된 경우만)
-- 변경 없으면 토스트 "변경 사항 없음", 변경 있으면 "동기화 완료"
+### 충돌 해결 (ConflictModal)
 
-설정이 안 됐으면 트레이 토스트로 안내. 한 번 설정하면 이후 push 는 OS credential helper 가 자동 처리.
+같은 노트를 두 기기에서 동시에 수정하면 path 별 결정 (내 것 / 원격) 을 받는다.
 
-데이터 라이프사이클 측면에서 F6-L1 (로컬 스냅샷, 자동) + F5/F6-L3 (수동 export/import) + F6-L2 (원격 git, 반자동) 3-layer 구조의 마지막 layer.
+- **내 것 사용**: 이 기기의 변경을 보존, 원격 변경을 폐기
+- **원격 사용**: 원격 변경을 가져오고, 이 기기의 변경을 폐기
+
+3 케이스:
+
+1. 편집/편집 — 양 텍스트 비교 후 더 새롭고 완전한 쪽 선택. 둘 다 보존하려면 한쪽 선택 + 사후 수동 병합 ('both' 미지원)
+2. 삭제/편집 — 삭제가 의도였으면 원격 사용 (trash 측), 수정이 더 중요하면 내 것 사용 (편집 측 = trash 취소)
+3. AI 결과 충돌 — 한쪽 선택 후 AI 재실행 권장
+
+### Silent risk
+
+- **시계 어긋남 (NTP)**: 양 기기 시계가 다르면 timestamp merge 가 잘못된 결과를 낼 수 있음. NTP 동기화 끄지 말 것
+- **두 기기 동시 수정 회피**: 같은 노트를 동시에 수정하면 conflict 가 잦아짐
+- **자동 sync 실패 silent**: 주기적 sync 실패 시 토스트 안 뜸. 마지막 sync 시각 / 결과는 설정 페이지에서 확인
+
+### Troubleshoot
+
+- **"연결 테스트" 실패** — 네트워크 (브라우저로 호스트 접속) / 인증 (SSH key 또는 token) / URL 오타 점검
+- **인증 실패 (push 안 됨)** — SSH 는 public key 등록 점검, HTTPS 는 OS credential helper (Windows Credential Manager / macOS Keychain) 의 저장 token 점검
+- **URL 변경** — 설정 페이지에서 새 URL 입력 → 저장 (`git remote set-url origin` 자동 처리)
+
+데이터 라이프사이클: F6-L1 (로컬 스냅샷, 자동) + F5/F6-L3 (수동 export/import) + F21 Cut E (양방향 git sync) 3-layer 구조.
 
 ---