snapshot-user

name	snapshot-user
description	Operate the `snapshot` per-service backup orchestrator — enable / list / take / restore / push / pull backups for file trees, postgres databases, wireguard configs, and (filed) filesystem-level snapshots. Trigger when the user wants to schedule backups, restore from a prior snapshot, sync backups across accounts, or learn the per-service plugin model.

snapshot-user skill

1. Design principles

• Educational. Each service is a small libexec plugin you can read end-to-end.
• Functional. Every verb is a thin wrapper over the underlying primitive (rsync, pg_dump, cp).
• Decentralized. Each account holds its own snapshot store; sync is symmetric pull/push.
• Simple. snapshot calls only account at runtime; SSH endpoints from account remote-url.

2. The model

A service is a backup-able state class. Today:

Service	Plugin	Backend
file	libexec/snapshot/file	rsync(1)
postgres	libexec/snapshot/postgres	pg_dump(1)
wireguard	libexec/snapshot/wireguard	cp /etc/wireguard
zfs/btrfs/lvm	(filed FEAT-058; pending)	filesystem snapshots

Backups live under $XDG_DATA_HOME/snapshot/<service>/, named with a timestamp. Retention follows max-backups (grandfather-father-son per FEAT-059, pending).

3. Workflow recipes

1. List supported services.

   snapshot services
   

2. Enable a service.

   snapshot enable postgres
   snapshot enabled postgres
   

3. Take a backup.

   snapshot backup postgres
   snapshot last postgres
   

4. Restore.

   snapshot restore postgres
   

5. Garbage-collect old backups.

   snapshot clean
   snapshot used
   snapshot free
   

6. Push to a peer.

   snapshot push postgres [e-mail]
   snapshot pull postgres [e-mail]
   snapshot remote [e-mail]
   

4. Guardrails

1. snapshot restore overwrites live state. Take a fresh backup first.
2. snapshot clean is irreversible — it removes old backup files per the retention policy.
3. Per-service config lives at $SELF_CONFIG/<service> — manual edits there change behaviour; check what's there before tweaking.
4. Pull respects account online — silently warn-and-skip if the peer is unreachable.
5. Filesystem-snapshot services aren't implemented yet (FEAT-058 pending). Use file/postgres/ wireguard today; ZFS/btrfs/LVM after that ticket lands.

5. Where to read more

• man snapshot
• man msync for the sync-trio sibling
• This package's CLAUDE.md