From df02f8a4412aa1df7c1637f709694a705e2bb977 Mon Sep 17 00:00:00 2001
From: claude-timemachine <llm@timemachine.center>
Date: Tue, 2 Jun 2026 22:33:25 +0200
Subject: [PATCH] design: lock client on-disk layout under
 <pack-folder>/.cloud-sync/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per-instance isolation (different Discord accounts for different MC
instances), auto-excluded from cloud sync, single 'rm -rf' reset.
Restic binary discovery probes pinned path → $PATH → upstream download.
---
 DESIGN.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/DESIGN.md b/DESIGN.md
index 38147b7..7797f1c 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -113,6 +113,40 @@ discord-bot's `/register` flow extends to call `POST cloud-svc:9091/admin/users`
 
 Revocation = operator runs `automc-setup cloud revoke <discord_id>` which hits the loopback admin port. No token store, no scope checks, no auth-service involvement.
 
+## On-disk layout (client)
+
+cloud-sync.jar stores its state under `<pack-folder>/.cloud-sync/` — per-instance, hidden by leading dot. Auto-excluded from cloud sync so a player can't accidentally upload their own credentials.
+
+```
+<pack-folder>/
+  mods/                              # managed by packwiz
+  config/                            # mixed: pack-shipped + player-modified
+  options.txt
+  journeymap/data/
+  .cloud-sync/                       # cloud-sync owns this
+    token                            # "discord_id:password" (mode 0600)
+    scope.json                       # per-distribution include/exclude rules
+    restic-<version>                 # auto-downloaded binary
+    state.json                       # last-pull snapshot ID, last-push time
+    logs/                            # rolling, capped ~5 MB
+```
+
+Per-instance isolation matters: a player running a cracked instance + a premium instance gets two separate `.cloud-sync/` dirs with different Discord credentials. `rm -rf .cloud-sync/` resets one instance entirely.
+
+### Restic binary discovery
+
+Probed in order:
+
+1. `<pack-folder>/.cloud-sync/restic-<version>` — pinned copy from first run
+2. `$PATH` (`which restic` + version match) — honor existing system install
+3. Download from `github.com/restic/restic/releases/download/v<version>/restic_<version>_<os>_<arch>.bz2`, cache to `<pack-folder>/.cloud-sync/`
+
+`--restic-binary <path>` flag overrides discovery for air-gapped operators.
+
+### Jar placement
+
+Stateless. Lives wherever the operator put it. Prism / MMC config references absolute path. One jar can serve N instances; each gets its own `.cloud-sync/` underneath its own `--pack-folder`.
+
 ## Client flow
 
 ### `cloud-sync.jar pull`