docs(spec): sync 도움말 v0.3.4 — SyncHelpModal + ConflictModal inline + README

3 표면 (in-app modal + ConflictModal inline + README) 통합 도움말.
4 시나리오 카테고리: 메인 conflict / 자동 처리 / silent risk / setup·인증.
ConflictModal local/remote 각 옵션 inline 설명 + "자세히 보기" 링크 →
SyncHelpModal anchor jump.

다기기 dogfood 의 핵심 가치 검증 (sync) 인데 막힌 순간 도움말 부재 →
v0.3.0 Cut E + v0.3.3 hotfix 기반 공식 도움말.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-05-10-sync-help-design.md

@@ -0,0 +1,138 @@
+# Sync 도움말 — Design
+
+날짜: 2026-05-10
+대상 버전: v0.3.4 (또는 v0.4.0 통합 시 Cut G 안에 포함)
+선행 의존: v0.3.0 Cut E (양방향 sync), v0.3.3 (configure-sync ENOENT hotfix)
+
+## 배경
+
+v0.3.0 Cut E 가 양방향 sync (configure UI + ConflictModal + auto-sync timer) 를 도입했지만, 사용자에게 노출되는 도움말은 다음 세 곳 모두 부족 또는 부재:
+
+- **SettingsPage > 동기화 저장소**: URL 입력 + 저장/연결 테스트 + 자동 sync 토글만 있음. 무엇이 어떻게 동작하는지 안내 0.
+- **ConflictModal**: "내 것 사용 (local)" / "원격 사용 (remote)" 버튼만 노출, 각 옵션의 의미·결과 미설명. 사용자는 추측에 의존.
+- **README "원격 백업 (F6-L2)" 섹션**: v0.2.1 MVP 시점 기준 (트레이 "지금 동기화" + 수동 `git init`). Cut E 의 Configure UI / ConflictModal / auto-sync timer 미반영 — 사용자가 따라하면 어긋남.
+
+다기기 (Mac + Windows) sync dogfood 는 본인 + 사내 베타 10인의 핵심 가치 검증인데, conflict 시나리오에 막혔을 때 도움말이 없어 사용자가 직접 git 내부 동작을 추측해야 하는 상태.
+
+## 목표
+
+git 기반 sync 의 정상 동작·이상 시나리오·복구 절차를 사용자가 막힌 순간에 바로 찾을 수 있게 만든다.
+
+비목표:
+
+- 'both' choice (v0.3.1+ deferred) 도움말
+- 다국어 (앱 한국어 only)
+- 스크린샷·GIF (텍스트만으로 충분)
+- README 외 docs/sync-guide.md 별도 파일 (in-app 이 메인, README 가 보조 — 별도 파일 발견성 ↓)
+
+## 표면 (3개)
+
+### 1. SyncHelpModal — 신규 컴포넌트
+
+**위치**: `src/renderer/inbox/components/SyncHelpModal.tsx`
+
+**진입점**:
+
+- `SyncSection.tsx`: URL 입력 row 옆에 "도움말" 버튼 추가 → 클릭 시 modal open
+- `ConflictModal.tsx`: 각 옵션 설명 옆 "자세히 보기 →" 링크 → SyncHelpModal open + "메인 conflict" 섹션으로 스크롤
+
+**구조**: `ConflictModal` 패턴 재사용 (overlay + 닫기 버튼 + scrollable body). 4 섹션 (단순 anchor jump — 좌측 nav 미도입, modal 무게 ↓):
+
+1. **메인 conflict** — 편집/편집, 삭제/편집, AI 결과 충돌 3 케이스 + 각 결정 트리
+2. **자동 처리** — fetch+rebase, 첫 sync 순서, push 순서 ("내가 안 해도 되는 일")
+3. **Silent risk** — 시계 어긋남(NTP), 결합 실패 silent, dogfood 주의
+4. **Setup/인증** — URL 형식 (SSH vs HTTPS), 인증 helper, 연결 실패 troubleshoot
+
+**Close**: ESC + 우상단 X + overlay 클릭 (ConflictModal 패턴 일치).
+
+### 2. ConflictModal 갱신
+
+**현재**: 각 conflict path 에 대해 "내 것 사용 (local)" / "원격 사용 (remote)" 버튼만.
+
+**변경**: 각 옵션 라벨 아래 1-2 줄 inline 설명 + "자세히 보기 →" 링크.
+
+```text
+내 것 사용 (local)
+  이 기기의 변경을 보존하고 원격의 같은 노트 변경을 폐기.
+  자세히 보기 →
+
+원격 사용 (remote)
+  원격 (다른 기기 또는 백업) 의 변경을 가져오고 내 변경을 폐기.
+  자세히 보기 →
+```
+
+"자세히 보기" 클릭 → SyncHelpModal open (메인 conflict 섹션 anchor).
+
+### 3. README "원격 백업 (F6-L2)" 섹션 통째 재작성
+
+**현재 (line 193-223)**: v0.2.1 MVP 기준 stale.
+
+**신규 헤더**: "## 동기화 (Git, F21 Cut E)"
+
+**하위 절**:
+
+- 일회 설정 — Settings > 동기화 저장소 UI 안내 (트레이 "지금 동기화" 안내 제거 — 현재 UI 와 다름)
+  - URL 형식 명확화: `git@host:user/repo.git` (SSH) 또는 `https://host/owner/repo.git` (HTTPS). v0.3.3 dogfood 에서 발견된 `git@https://` 혼합 오류 사례 명시
+- 일상 사용 — auto-sync 주기 / 수동 트리거 / 충돌 시 ConflictModal 안내
+- 충돌 해결 — local/remote 결정 트리 (in-app SyncHelpModal 과 같은 내용)
+- Silent risk — 시계 어긋남, 동시 수정 회피
+- Troubleshoot — push 실패 / 인증 실패 / 첫 sync 순서
+
+## 콘텐츠 분배
+
+| 시나리오 | SyncHelpModal | ConflictModal inline | README |
+|---|---|---|---|
+| 편집/편집 conflict | 결정 트리 (어떤 변경이 더 최신인지 / 둘 다 보존하려면 사후 수동 병합) | 1줄 + "자세히" 링크 | 상세 + 예시 |
+| 삭제/편집 | 케이스 설명 (삭제 측이 'remote' 면 trash 로 이동, 편집 측이 'local' 이면 trash 취소) | (해당 없음 — path 가 같음) | 케이스 설명 |
+| AI 결과 충돌 | "재처리 권장" — local/remote 한쪽 선택 후 AI 재실행 권장 | (해당 없음) | 케이스 설명 |
+| fetch+rebase 자동 | "내가 안 해도 되는 일" 단원 | — | 동일 |
+| 첫 sync 순서 | "Mac 먼저 push → Windows pull 후 push" | — | 동일 |
+| 시계 어긋남 (NTP) | "두 기기 동시 수정 회피", `chrony` / Windows time sync 점검 안내 | — | 동일 |
+| Setup/URL 형식 | SSH/HTTPS 예시, `git@https://` 같은 혼합 형식 거부 사례 | — | 동일 + 인증 helper 안내 |
+| 인증 실패 | "OS credential helper 점검", token URL embed 우회 옵션 | — | 동일 |
+
+## 변경 파일
+
+**신규**:
+
+- `src/renderer/inbox/components/SyncHelpModal.tsx`
+- `tests/unit/SyncHelpModal.test.tsx`
+
+**수정**:
+
+- `src/renderer/inbox/components/settings/SyncSection.tsx` — "도움말" 버튼 추가 (URL row 옆)
+- `src/renderer/inbox/components/ConflictModal.tsx` — 각 옵션 inline 설명 + "자세히" 링크
+- `tests/unit/ConflictModal.test.tsx` — inline 설명 / 링크 클릭 시 SyncHelpModal open 회귀
+- `tests/unit/SyncSection.test.tsx` — 도움말 버튼 클릭 → SyncHelpModal open 회귀
+- `README.md` — "원격 백업 (F6-L2)" 섹션 line 193-223 통째 재작성
+
+## 게이트
+
+- `SyncHelpModal.test.tsx` 신규 — 4 섹션 렌더링, close (ESC/X/overlay), anchor jump
+- `ConflictModal.test.tsx` 회귀 — inline 설명 표시, "자세히" 링크 → SyncHelpModal open
+- `SyncSection.test.tsx` 회귀 — 도움말 버튼 → SyncHelpModal open
+- typecheck 0
+- 단위 +6~8 (SyncHelpModal 4 + ConflictModal 회귀 1 + SyncSection 회귀 1)
+- e2e 미수행 (UI-only, 기존 capture/onboarding flow 무관)
+
+## Risk
+
+- **콘텐츠 정확성**: AI 결과 충돌 / 시계 어긋남 같은 시나리오는 dogfood 미경험 (v0.3.3 까지 1 dogfood 발견). 도움말이 실제 사용자 경험과 어긋날 risk → 1주 dogfood soak 후 도움말 텍스트 1차 갱신 필수
+- **README 와 in-app 의 중복 maintain**: 두 곳에 같은 내용. 정합성 깨질 risk → 우선순위는 in-app (사용자가 보는 위치). README 는 보조
+- **'both' choice 부재 안내**: v0.3.1+ deferred 인데 사용자가 "왜 둘 다 보존이 없냐" 질문 가능 → 도움말에 "현재 미지원, 사후 수동 병합" 명시
+- **콘텐츠 길이**: SyncHelpModal 4 섹션이 길어지면 modal 자체가 무거워짐 → 각 섹션 200 자 이내 + README 가 상세. modal 은 "막힌 순간 결정 트리" 우선
+
+## 비포함 / Deferred
+
+- 'both' choice 도움말 (Cut E 정책 deferred)
+- 다국어 (앱 한국어 only)
+- 스크린샷 / GIF
+- 별도 docs/sync-guide.md (README + in-app 으로 충분)
+- ConflictModal 의 diff 시각 개선 (별개 task, 본 도움말 cut 의 scope 외)
+- 도움말 검색 기능 (4 섹션, 짧음)
+
+## How to apply
+
+- v0.3.4 patch 또는 Cut G 안에 통합. 단독 cut 으로 갈 경우 v0.3.4 — 데이터/마이그레이션 변경 0
+- dogfood 1주 soak 후 도움말 텍스트 정합성 1차 갱신 (실제 사용자 경험과 어긋난 부분 보강)
+- ConflictModal 의 inline 설명은 "자세히 보기" 링크 한 번이 SyncHelpModal 메인 conflict 섹션 anchor 로 점프 — anchor id 명명: `#main-conflict`, `#auto`, `#silent`, `#setup`