pivot to Python: replace Kotlin/JVM with stdlib zipapp

Reasons stacked up:
  - AV: unsigned JARs that auto-download binaries + upload files trigger
    Windows Defender false-positives more often than Python scripts
    invoked by code-signed python.exe.
  - Qt UI option: PySide6 opens a path to a real Qt UI (matching Prism's
    look) if needed later. JVM Qt bindings are abandoned.
  - frazclient already needs Python; inlining as 'import cloud_sync' is
    zero overhead vs the launcher always shelling out to java.

Implementation:
  - cloud_sync package: cli.py (argparse), creds.py, scope.py,
    restic.py (binary discovery + auto-download + sha256 verify),
    sync.py (pull/push subprocess restic).
  - pyproject.toml with hatchling backend; pip-installable.
  - Makefile builds cloud-sync.pyz via python -m zipapp (~53 KB).
  - 33 pytest tests, stdlib only on runtime.
  - CI workflow runs pytest matrix (3.10/3.11/3.12) + builds pyz.
  - DESIGN.md + README.md updated to reflect Python.

E2E verified against local restic-rest-server:
  pull empty → push initial → rm -rf local → pull restores → modify+push
  creates second snapshot → client forget --prune blocked by --append-only.

Throws away ~565 LOC of Kotlin (and 18 jar tests) committed earlier in
this same session. Net result is ~250 LOC Python + 33 tests = smaller
and more aligned with the rest of the stack.

README.md

@@ -1,80 +1,100 @@
 # cloud-sync
 
-Single-jar Kotlin client for [`cloud-svc`](https://git.timemachine.center/Timemachine/cloud-svc). Drops into Prism / MMC / ATLauncher / frazclient pre-launch + post-exit hooks alongside [`packwiz-installer-bootstrap`](https://github.com/packwiz/packwiz-installer-bootstrap). One tool, all launchers, no Python dependency on the client side.
+Per-user Minecraft state sync via [restic](https://restic.net). Single Python zipapp drops into Prism / MMC / ATLauncher pre-launch and post-exit hooks alongside [packwiz-installer-bootstrap](https://github.com/packwiz/packwiz-installer-bootstrap). Part of the [automc](https://git.timemachine.center/Timemachine/automc) platform.
+
+See [`DESIGN.md`](DESIGN.md) for the full architecture (restic backend, two-port cloud-svc control plane, etc.).
 
 ## Status
 
-**Skeleton.** Build works, jar runs, CLI parses subcommands. Real sync logic + conflict UI land in subsequent commits. See [`DESIGN.md` in cloud-svc](https://git.timemachine.center/Timemachine/cloud-svc/src/branch/main/DESIGN.md) for the underlying contract this jar implements.
+Working skeleton + sync logic. 33 tests pass. E2E verified against a local `restic-rest-server` (pull empty → push initial → delete local → pull restores → modify+push creates second snapshot → client `forget --prune` correctly blocked by `--append-only`).
 
-## Usage (planned)
+## Install / build
 
-In Prism's instance settings → Custom commands:
+Requires Python ≥ 3.10. No runtime deps (stdlib only).
 
-```
-Pre-launch command:
-  "$INST_JAVA" -jar /path/to/cloud-sync.jar pull \
-      --url=https://cloud.timemachine.center \
-      --pack-folder=$INST_MC_DIR
+```bash
+# build single-file zipapp
+make build       # → cloud-sync.pyz (~53 KB)
 
-Post-exit command:
-  "$INST_JAVA" -jar /path/to/cloud-sync.jar push \
-      --url=https://cloud.timemachine.center \
-      --pack-folder=$INST_MC_DIR
+# or pip-install
+make install     # pip install -e .
 ```
 
-Token comes from `$INST_MC_DIR/.cloud-token` (paste once from your Discord-bot DM), `--token <STR>`, or `CLOUD_TOKEN` env.
+## Usage in Prism (or MMC / ATLauncher)
+
+Instance Settings → Custom commands:
+
+```
+Pre-launch:
+  python /path/to/cloud-sync.pyz pull --url=https://cloud.tm.center --pack-folder=$INST_MC_DIR
+
+Post-exit:
+  python /path/to/cloud-sync.pyz push --url=https://cloud.tm.center --pack-folder=$INST_MC_DIR
+```
+
+Player needs Python 3.10+ on PATH. Token file (`<INST_MC_DIR>/.cloud-sync/token`) gets the `discord_id:password` credentials from their `/register` Discord DM.
 
 ## CLI
 
 ```
-java -jar cloud-sync.jar <subcommand> [flags]
-
-Subcommands:
-  pull     Fetch user's cloud state, apply conflict resolution, write to instance.
-  push     Walk instance, build snapshot, upload changed files.
-
-Flags:
-  --url <URL>           cloud-svc base URL (required)
-  --pack-folder <DIR>   instance dir to sync into/from (default: ".")
-  --token <STR>         bearer token (or use --token-file)
-  --token-file <PATH>   read token from this file (default: <pack-folder>/.cloud-token)
-  -g, --no-gui          headless mode; conflicts auto-resolve to remote-wins
-  -V, --version         print version
-  -h, --help            print this help
+python cloud-sync.pyz {pull,push} \
+    --url URL              cloud-svc data plane URL (required)
+    --pack-folder PATH     Minecraft instance directory (default: cwd)
+    --token-file PATH      override default <pack-folder>/.cloud-sync/token
+    --restic-binary PATH   skip auto-discovery
+    --no-download          fail if no usable restic; don't fetch from upstream
+    -g, --no-gui           headless mode
 ```
 
-## Build
+## Programmatic API (for frazclient)
 
-Requires JDK 17–21 (JDK 26 currently breaks Kotlin 2.1's compiler). Easiest: containerized via podman/docker.
+```python
+from pathlib import Path
+import cloud_sync
 
-```bash
-podman run --rm -v "$PWD":/work:Z -w /work docker.io/gradle:8.10.2-jdk21 \
-    gradle --no-daemon shadowJar
+cloud_sync.pull(cloud_sync.Args(
+    url="https://cloud.tm.center",
+    pack_folder=Path("/srv/mc/instance"),
+    token_file=Path("/srv/mc/instance/.cloud-sync/token"),
+    restic_binary=None,        # auto-discover
+    allow_download=True,
+    headless=True,
+))
 ```
 
-Output: `build/libs/cloud-sync-<version>.jar`. Single fat jar; ship as-is.
+frazclient's `client.py` consumes this directly via `import cloud_sync` instead of subprocessing the pyz.
 
-For local development with a matching JDK installed:
+## On-disk layout
 
-```bash
-./gradlew shadowJar
+Per-instance state under `<pack-folder>/.cloud-sync/`:
+
+```
+.cloud-sync/
+  token                       # discord_id:password (mode 0600)
+  scope.json                  # optional; defaults baked in if missing
+  restic-<RESTIC_VERSION>      # auto-downloaded binary
+  files-from.txt              # restic --files-from
+  exclude-from.txt            # restic --exclude-from
 ```
 
-## UI
+Auto-excluded from sync. Multiple MC instances = multiple `.cloud-sync/` dirs with independent credentials.
 
-Swing + [FlatLaf](https://www.formdev.com/flatlaf/) (`FlatMacDarkLaf` theme). Closest visual match to Prism's Qt look in pure Java. Falls back to system look-and-feel if FlatLaf init fails (e.g., on bare-bones X servers).
+## Why Python (not a JAR)
 
-Conflict resolution dialog: per-file [keep local | use remote | skip] radio buttons + "use all local/remote" + Cancel/Continue. Headless mode (`-g`) defaults all conflicts to remote-wins (Steam's default).
+1. **Antivirus.** Unsigned JARs that auto-download binaries + upload files are textbook Windows Defender false-positive triggers. Python invoked by code-signed `python.exe` mostly sidesteps that.
+2. **Future Qt UI.** PySide6 opens a path to a real Qt UI (matching Prism's look) if richer surfaces are wanted later. JVM Qt bindings are abandoned.
+3. **frazclient already needs Python.** Inlining as an import is zero overhead; the same package serves Prism via the pyz.
 
-## Where this fits in the automc stack
+Cost: players using Prism must have Python 3.10+ installed. Most Linux/Mac systems already do; Windows users install once from the Microsoft Store or python.org.
 
-| Tool | What it owns |
-|---|---|
-| **packwiz-installer-bootstrap** | Mod sync — jars, configs shipped by the modpack, options.txt baseline |
-| **cloud-sync** (this) | Per-user sync — player-modified configs, JourneyMap waypoints, screenshots |
-| **frazclient** | Cracked-launcher orchestration — JDK, vanilla MC, Fabric, then invokes both jars |
+## Where the data lives
 
-cloud-sync and packwiz-installer-bootstrap are deliberately **separate jars** so players can disable cloud sync without affecting modpack sync (or vice versa) by just commenting out the line in Prism's hook config.
+| Component | Role | Repo |
+|---|---|---|
+| `cloud-sync` (this) | Player-side. Subprocess restic for pull/push. | `Timemachine/cloud-sync` |
+| `cloud-svc` | Operator-side control plane (provisioning + admin). | `Timemachine/cloud-svc` |
+| `restic-rest-server` (existing) | Data plane. Player's restic hits it directly with their password. | upstream |
+| `discord-bot` | Calls cloud-svc on `/register` to provision a player's cloud account. | `Timemachine/discord-bot` |
 
 ## License