msync-user

name	msync-user
description	Operate the `msync` snapshot-based bidirectional sync tool — sync two paths between machines using a three-way merge. Trigger when the user wants to keep a notes / docs / config directory in sync across two accounts, recover from a sync conflict, or learn the three-way-merge model.

msync-user skill

1. Design principles

• Educational. A small ~184-line dispatcher that composes data table operations and rsync. Reading end-to-end teaches the snapshot-based three-way merge.
• Functional. Pure transformations over snapshot files; no in-place state changes during a msync sync.
• Decentralized. Two-way sync between peers; no central server.
• Simple. msync calls only account and data. The data dep is the documented exception to the strict-foundation rule; FEAT-046 will inline it.

2. The model

A snapshot is a TSV table:

File	Mtime	Size	Hash
notes/intro.md	1714723200	845	abc123
notes/index.md	1714723300	120	def456
...

msync sync a b runs three snapshots — base, A's current, B's current — and computes a three-way merge on the union of file paths:

• File only in A ⇒ copy to B
• File only in B ⇒ copy to A
• File in both, identical ⇒ skip
• File in both, different ⇒ conflict

Conflict policy: today, mtime + size win (newer + larger preferred). Per FEAT-064, richer policies (interactive, batch, --theirs / --ours flags) will land later.

3. Workflow recipes

1. Take a snapshot of a tree.

   msync snapshot ~/notes
   

2. Sync two paths.

   msync sync ~/notes peer:~/notes
   

3. Sync via an intermediate account.

   msync sync ~/notes peer:~/notes [e-mail]
   

4. Schedule via event.

   event create notes-sync
   event edit   notes-sync
   # script body: msync sync ~/notes peer:~/notes
   echo '*/15 * * * *' | event insert notes-sync schedule
   

4. Guardrails

1. Conflict policy is mtime + size today. If both sides have a newer-but-smaller file, the larger wins. This may be wrong for your workload — wait for FEAT-064 if you need stricter policy.
2. msync sync is two-way. Don't run it concurrently from both ends; you'll race the snapshot computation.
3. Multi-endpoint (N≥2) isn't implemented (FEAT-065 pending). Stick to two-way until that lands.
4. Snapshots include mtime, not content hash. A touch-only edit (no content change) still triggers a sync. Filter via --exclude patterns if that matters.
5. Bsync (the Python predecessor) is being phased out per FEAT-063. Migrate to msync; bsync stays for backward compat in v0 but won't get new features.

5. Where to read more

• man msync
• man snapshot for the per-service-backup sibling
• man data — table operations msync uses internally
• This package's CLAUDE.md