Initial SyncGames tree: agent, Android, deploy, docs.

Session-gated MinIO save sync with AppImage GUI, CLI edit/session flow, and Gitea release helper. Co-authored-by: Cursor <[email protected]>
2026-07-14 22:06:36 -05:00
commit 0d6b0b2f80
76 changed files with 5697 additions and 0 deletions
@@ -0,0 +1,83 @@
+# 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).