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

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 설명 + "자세히 보기 →" 링크.

내 것 사용 (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