# SyncGames

Session-gated save sync for Steam (incl. Seamless Coop) and emulator titles across Linux PCs/laptops and Android.

**Architecture:** Path 3 — MinIO SSOT on NAS, Python agent on Linux, light Kotlin UI on Android.  
**Ingress:** Cloudflare → Tunnel → NGINX → MinIO (WAN HTTPS, no VPN required).

## Safety model

1. **Pull** SSOT into the game’s native save path only at session start.
2. Play against local WIP only.
3. **Push** WIP to SSOT only at session end (history slot + live promote).
4. One **lease** per game; hash gate blocks stale WIP overwrites.
5. Per-device history keeps the last N versions (default 5) for LOPE recovery.

Never point continuous sync tools at live game save directories.

## Download (multi-device)

Repo: [git.hisora.dev/Dawnsorrow/SyncGames](https://git.hisora.dev/Dawnsorrow/SyncGames)

Grab the latest **Release** assets (AppImage / APK) — do not commit binaries into git.

```bash
# Linux
chmod +x SyncGames-*-x86_64.AppImage
./SyncGames-*-x86_64.AppImage
```

Use the **Setup** tab for endpoint/keys, **Games** to add/edit titles, **Session** for start/end/restore.

## Quick start (Linux)

### Build AppImage from source

```bash
cd agent
./packaging/build-appimage.sh
# → agent/dist/SyncGames-*-x86_64.AppImage
```

### CLI / editable install

```bash
cd agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[gui]"

syncgames-gui          # thin management UI
# or: syncgames gui

cp ../config/agent.toml.example ~/.config/syncgames/agent.toml
syncgames doctor
```

## Docs

| Doc | Purpose |
|-----|---------|
| [docs/architecture.md](docs/architecture.md) | System overview |
| [docs/protocol.md](docs/protocol.md) | Shared SSOT protocol (Python ↔ Android) |
| [docs/nas-minio-cloudflare.md](docs/nas-minio-cloudflare.md) | MinIO + NGINX + Cloudflare |
| [docs/add-game.md](docs/add-game.md) | Add / remove games |
| [docs/fallback-path1.md](docs/fallback-path1.md) | Syncthing fallback |
| [docs/planning/](docs/planning/) | Planning archive |

## Layout

```
SyncGames/
  agent/          Python CLI + thin GUI (+ AppImage packaging)
  android/        Kotlin/Compose light UI
  config/         Device + game TOML
  deploy/
    docker/       Docker Compose (MinIO SSOT)
    nginx/        Example NGINX vhost
  systemd/        User units for watchers
  docs/
```

## MinIO / NAS Docker

See [deploy/docker/README.md](deploy/docker/README.md) for Compose (`MinIO` on `127.0.0.1:9000` behind your existing NGINX).