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,63 @@
+# Path drafts — three architectures
+
+Original comparison before Path 3 was selected.
+
+## Non-negotiable session model
+
+Every viable design shares the same state machine. Continuous bidirectional sync of **live** save directories is the antipattern that caused prior LOPEs.
+
+- Pull only at session start; push only at session end
+- One lease per game
+- Hash gate rejects stale WIP unless explicit force-restore
+- Per-device history (3–5 versions); single live SSOT slot
+- Never delete live without first moving current into history
+
+### Conceptual layout
+
+```
+games/<game-id>/
+  live/              # SSOT current slot
+  history/<device>/  # last N snapshots per device
+  meta.json
+```
+
+---
+
+## Path 1 — Hardened Syncthing + Session Orchestrator
+
+Syncthing syncs only the **SSOT tree**, never native game save dirs. A local agent copies native ↔ WIP ↔ SSOT around sessions.
+
+**Pros:** Fast LAN; mature Android Syncthing client.  
+**Cons:** Discipline required; peer conflict resolution if lease fails.  
+**Status:** Named **fallback** if MinIO/WAN path becomes blocking.
+
+---
+
+## Path 2 — Custom Agent + Gitea (Git LFS)
+
+Gitea as SSOT; saves as LFS or release assets; agent pull/push around sessions.
+
+**Pros:** Auditable history in web UI.  
+**Cons:** Git/LFS friction for binaries.  
+**Status:** Shelved.
+
+---
+
+## Path 3 — Custom Agent + MinIO (selected)
+
+SSOT is versioned object storage on NAS MinIO. Agent implements pull-live / push-live / history / restore. Exposed via Cloudflare → NGINX → MinIO for WAN.
+
+**Pros:** Cleanest binary SSOT model; no Git merge footguns; easy prune.  
+**Cons:** Own the agent end-to-end; need reachable HTTPS API.  
+**Status:** **Building this.**
+
+### Comparison snapshot
+
+| Tenet | Path 1 | Path 2 | Path 3 |
+|-------|--------|--------|--------|
+| Safety / direction | High if SSOT-only | High | Highest |
+| Automation | Excellent Linux | Good | Excellent |
+| Easy add/remove | CLI + Syncthing API | CLI + repo | CLI + key prefixes |
+| LOPE recovery | history + .stversions | git/local history | object history |
+| Android | Syncthing-Fork | Custom app | Custom Compose app |
+| Past LOPE risk | Medium if live dirs synced | Low | Low |