memory-toast-make-card 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smallseven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# memory-toast-make-card
+
+A [Claude Code](https://claude.com/claude-code) skill that turns your study material —
+requirements, web research, PDFs, images, notes — into [Memory Toast](https://memory-toast-api.smallseven-87b.workers.dev)
+flashcard decks (卡包), optionally **generates card images with your own OpenAI/Gemini key**,
+and uploads the deck to **your** Memory Toast account as a ZIP pack.
+
+It is the public, token-authenticated counterpart of the internal `make-card` skill: you sign
+in once with your own account, and your password is never stored — only a rotating refresh token.
+
+## Install
+
+### Option A — npm
+
+```bash
+# Into your user skills (~/.claude/skills/)
+npx memory-toast-make-card install
+
+# Or into the current project (./.claude/skills/)
+npx memory-toast-make-card install --project
+```
+
+### Option B — skills.sh
+
+Install from the registry, or copy the folder into `~/.claude/skills/memory-toast-make-card/`
+manually. The skill is the directory containing `SKILL.md`.
+
+## Prerequisites
+
+1. **A Memory Toast account** — the same one you use in the app.
+2. **Log in once** (stores a refresh token in `~/.memory-toast/credentials.json`, chmod 600;
+   no secret is written to disk except the rotating token):
+   ```bash
+   # Email/password account:
+   python3 ~/.claude/skills/memory-toast-make-card/scripts/mt_login.py
+
+   # Google/Facebook account (no password): copy the token from the app
+   # (Settings → Copy upload token), then paste it here:
+   python3 ~/.claude/skills/memory-toast-make-card/scripts/mt_login.py token
+   ```
+   `mt_login.py whoami` shows the logged-in account; `mt_login.py logout` removes the token.
+3. **(Optional) image generation** — export your own key for the provider you want:
+   ```bash
+   export OPENAI_API_KEY=sk-...      # OpenAI gpt-image-1
+   export GEMINI_API_KEY=...         # Google Imagen / Gemini
+   ```
+   You always supply your own key; the skill never provides one. Image generation calls a
+   **paid** API — the skill confirms the cost with you before generating in bulk.
+
+## Usage
+
+In Claude Code, just ask — for example:
+
+> Make a Memory Toast deck of 30 common Japanese N3 verbs, each with a flat-vector icon image.
+
+The skill will gather requirements, draft a few sample cards for your approval, generate any
+images (with your confirmation on cost), build the ZIP, and upload it. Then open the deck in
+the Memory Toast app and tap **Download** on the "new version available" banner.
+
+You can also drive the scripts directly:
+
+```bash
+S=~/.claude/skills/memory-toast-make-card/scripts
+
+# Generate an image with your own key
+python3 $S/gen_image.py --provider openai \
+  --prompt "flat vector icon of a person eating, warm palette, white background" \
+  --out my-deck/assets/taberu.png
+
+# Validate a deck directory offline (builds my-deck/build/pack.zip)
+python3 $S/upload_pack.py my-deck --dry-run
+
+# Create a new deck and upload
+python3 $S/upload_pack.py my-deck
+
+# Update an existing deck (needs its current server version)
+python3 $S/upload_pack.py my-deck --deck-id <id> --local-version <serverVersion>
+```
+
+See [`references/pack-format.md`](references/pack-format.md) for the `deck.json` schema, the
+upload protocol, limits, and version/conflict rules.
+
+## Configuration
+
+- **Server URL** resolves as: `--api` flag → `MEMORY_TOAST_API_URL` env → stored value →
+  built-in default. Self-hosters can point the skill at their own server without editing files.
+- **Image model** is overridable with `--model`. Defaults: `gpt-image-1` (OpenAI),
+  `imagen-4.0-generate-001` (Gemini). Pass a `gemini-*-image` model (e.g.
+  `gemini-2.5-flash-image`) to use the `generateContent` path instead of Imagen `predict`.
+  > Note: Google's older image-generation model endpoints are deprecated after **2026-06-30** —
+  > switch the default via `--model` if generation starts failing.
+
+## Security notes
+
+- The password is read interactively (never echoed) and **never stored** — only the rotating
+  7-day refresh token, in a `chmod 600` file under your home directory. `logout` deletes it.
+- API keys and tokens are never printed; error paths redact them.
+- These are **stateless JWTs**: a leaked refresh token cannot be individually revoked before
+  its 7-day expiry. Keep the credential file private and run `logout` on shared machines.
+- An upload **replaces** the deck's server pack wholesale — push any un-synced phone edits
+  first (see pack-format.md §5).
+
+## Requirements
+
+- Python 3.9+ (standard library only — no `pip install`).
+- Node 16+ (for the `npx` installer only).
+
+## License
+
+MIT — see [LICENSE](LICENSE). (Copyright holder is set to `smallseven`; edit it if you'd
+rather publish under a different name/org.)

package/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: memory-toast-make-card
+description: Create Memory Toast flashcard decks (卡包) from the user's requirements, web research, or their own data (PDFs, images, notes) — optionally generating card images with the user's own OpenAI/Gemini key — then upload them to the user's Memory Toast account as ZIP packs via the API. Use when the user asks to make cards, build a deck/卡包, turn study material into flashcards, generate card images, or upload a deck to Memory Toast.
+---
+
+# Make Card — Memory Toast deck builder & uploader
+
+Build a flashcard deck as a local "deck directory" (`deck.json` + media), confirm the card
+format with the user via samples, optionally generate images with the user's own API key,
+then build + upload the ZIP pack with `scripts/upload_pack.py`.
+
+The authoritative spec for formats, the API protocol, limits, and conflict rules is
+[references/pack-format.md](references/pack-format.md) — read it before writing `deck.json`
+or debugging an upload. **Converse in the user's language** even though these docs are in English.
+
+## Prerequisites (one-time)
+
+- **Account:** the user needs a Memory Toast account (the same one they use in the app).
+- **Login (email/password):** `python3 scripts/mt_login.py` — prompts once, then stores a
+  rotating refresh token in `~/.memory-toast/credentials.json` (chmod 600). The password is
+  never stored. **Never ask for or handle the user's raw password yourself — the helper does.**
+- **Login (Google/Facebook users):** these accounts have no password. In the app, go to
+  **Settings → Copy upload token**, then run `python3 scripts/mt_login.py token` and paste it.
+- `mt_login.py whoami` shows who is logged in; `mt_login.py logout` clears it.
+- **Image keys (only if generating images):** the user exports their own
+  `OPENAI_API_KEY` or `GEMINI_API_KEY`. You never provide a key.
+
+## Workflow
+
+### 1. Gather requirements
+
+Ask (in the user's language) only what is missing, one item at a time:
+
+- Topic and scope (e.g. "50 N3 verbs" vs. "this whole PDF").
+- Deck title, description, tags, language (default `zh-TW`).
+- Data source: user-provided files (PDF/images/notes) or web research.
+- Whether cards should have **generated images** — and if so, the visual style
+  (e.g. flat vector icon, watercolor, photoreal) and which provider (OpenAI / Gemini).
+
+### 2. Collect data
+
+- **User files:** read PDFs/images directly and transcribe (a dedicated `pdf` skill is
+  optional, not required).
+- **Web research:** use WebSearch/WebFetch. Verify factual content (dates, definitions,
+  translations) against at least one more source.
+- Any downloaded media for a card goes into the deck directory (e.g. `my-deck/assets/`),
+  referenced by relative path in `deck.json`.
+
+### 3. Confirm card format with examples (MANDATORY before mass production)
+
+1. Ask the user for a front/back example of how they want cards to look (or whether to copy
+   an existing deck's style).
+2. Draft 2–3 sample cards from the **actual data** and show them as front/back text (plus any
+   planned sections) in chat.
+3. Wait for explicit approval or corrections, then apply the approved pattern to ALL cards.
+
+Audio sections: do NOT add decorative captions (e.g. "聽發音 🔊") — the app renders a
+self-explanatory play button. Use a caption only when it carries real information.
+
+### 4. Generate images (optional — only if requested)
+
+1. Confirm the relevant key is set: `python3 scripts/gen_image.py --provider openai --prompt x
+   --out /tmp/probe.png --dry-run` (reports `key=set` or errors). If missing, tell the user the
+   exact env var to export.
+2. **Cost gate (MANDATORY):** before generating, tell the user *"this will call your
+   `<provider>` key ~N times (~$X) — proceed?"* and wait for a yes. Image generation spends the
+   user's money.
+3. Generate **one image at a time**, writing into the deck's `assets/`:
+   ```bash
+   python3 scripts/gen_image.py --provider openai \
+     --prompt "flat vector icon of a person eating, warm palette, white background" \
+     --out my-deck/assets/taberu.png
+   ```
+   - OpenAI default model `gpt-image-1`; Gemini default `imagen-4.0-generate-001`
+     (override with `--model`).
+   - If one image fails (rate limit, content policy), leave that card text-only and continue;
+     report which cards got no image.
+4. Reference each generated PNG as a normal local image section in `deck.json`
+   (`{ "kind": "image", "file": "assets/taberu.png" }`).
+
+### 5. Build the deck directory + validate (no network)
+
+Create a working directory (e.g. `/tmp/make-card/<slug>/` or a user-specified path) with
+`deck.json` (schema in pack-format.md §3) and any `assets/`. Do NOT hand-write UUIDs,
+positions, `storageRef`, or `mimeType` — the script generates them. Then:
+
+```bash
+python3 scripts/upload_pack.py <deck-dir> --dry-run
+```
+
+Fix any validation errors. The built ZIP lands at `<deck-dir>/build/pack.zip`.
+
+### 6. Upload
+
+```bash
+# New deck (creates the deck, uploads pack version 1)
+python3 scripts/upload_pack.py <deck-dir>
+
+# Update an existing deck — needs the current server version
+python3 scripts/upload_pack.py <deck-dir> --deck-id <id> --local-version <serverVersion>
+```
+
+On a 409 conflict the script prints the server version and the exact retry command.
+**Before updating an existing deck, warn the user:** the upload replaces the server pack
+wholesale; un-synced edits on the phone are overwritten on the next pull (pack-format.md §5).
+
+If the script says the session expired, run `python3 scripts/mt_login.py` again.
+
+### 7. Report
+
+Tell the user: deck title, card count, media count, ZIP size, deck id, pack version, and
+remind them to pull the deck in the app (open the deck → top banner "new version available" →
+tap Download).

package/bin/install.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Installer for the memory-toast-make-card Claude skill.
+ *
+ *   npx memory-toast-make-card install            # → ~/.claude/skills/
+ *   npx memory-toast-make-card install --project  # → ./.claude/skills/
+ *   npx memory-toast-make-card install --dir PATH # → PATH/
+ *
+ * Copies SKILL.md + scripts/ + references/ into a Claude skills directory.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SKILL_NAME = 'memory-toast-make-card';
+const PAYLOAD = ['SKILL.md', 'scripts', 'references'];
+const SKIP = new Set(['__pycache__', 'build', '.DS_Store']);
+const pkgRoot = path.resolve(__dirname, '..');
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      if (SKIP.has(entry) || entry.endsWith('.pyc')) continue;
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args.find((a) => !a.startsWith('-')) || 'install';
+  if (cmd !== 'install') {
+    console.error(`Unknown command "${cmd}".`);
+    console.error(`Usage: npx ${SKILL_NAME} install [--project] [--dir <path>]`);
+    process.exit(1);
+  }
+
+  let baseDir;
+  const dirIdx = args.indexOf('--dir');
+  if (dirIdx !== -1 && args[dirIdx + 1]) {
+    baseDir = path.resolve(args[dirIdx + 1]);
+  } else if (args.includes('--project')) {
+    baseDir = path.resolve(process.cwd(), '.claude', 'skills');
+  } else {
+    baseDir = path.join(os.homedir(), '.claude', 'skills');
+  }
+
+  const target = path.join(baseDir, SKILL_NAME);
+  for (const item of PAYLOAD) {
+    const src = path.join(pkgRoot, item);
+    if (!fs.existsSync(src)) {
+      console.error(`ERROR: missing payload "${item}" in package at ${pkgRoot}`);
+      process.exit(1);
+    }
+    copyRecursive(src, path.join(target, item));
+  }
+
+  console.log(`Installed "${SKILL_NAME}" skill → ${target}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  1. python3 "${path.join(target, 'scripts', 'mt_login.py')}"   # log in once`);
+  console.log('  2. (optional) export OPENAI_API_KEY or GEMINI_API_KEY to generate card images');
+  console.log('  3. In Claude Code, ask: "make a Memory Toast deck about <topic>"');
+}
+
+main();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "memory-toast-make-card",
+  "version": "0.1.0",
+  "description": "Claude Code skill to build Memory Toast flashcard decks (卡包) — with optional AI image generation using your own OpenAI/Gemini key — and upload them to your Memory Toast account.",
+  "bin": {
+    "memory-toast-make-card": "bin/install.js"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "scripts/*.py",
+    "references/*.md",
+    "bin/*.js"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-skill",
+    "agent-skill",
+    "flashcards",
+    "spaced-repetition",
+    "memory-toast",
+    "anki",
+    "study"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/references/pack-format.md

@@ -0,0 +1,168 @@
+# Memory Toast pack format & upload protocol
+
+Authoritative spec for the `memory-toast-make-card` skill: the ZIP pack structure, the
+`deck.json` input format, and the full API upload flow. Read this before writing
+`deck.json` or debugging an upload.
+
+## Contents
+
+1. [ZIP pack structure](#1-zip-pack-structure)
+2. [cards.json schema](#2-cardsjson-schema)
+3. [deck.json — the skill's input format](#3-deckjson--the-skills-input-format)
+4. [Upload protocol (API)](#4-upload-protocol-api)
+5. [Versioning & conflicts](#5-versioning--conflicts)
+6. [Limits & validation](#6-limits--validation)
+
+## 1. ZIP pack structure
+
+Each deck's full content is packaged into a single ZIP. The server stores deck metadata
+and pack-version records only — it never parses the ZIP body.
+
+```
+pack.zip
+├── manifest.json        # deck-level metadata
+├── cards.json           # all cards + sections
+└── media/               # local media files, named {sectionId}.{ext}
+    ├── 3f2a…c1.jpg
+    └── 9b07…e4.mp3
+```
+
+`manifest.json` (provenance only — the app does not validate `builtBy`):
+
+```json
+{
+  "schemaVersion": 1,
+  "deckTitle": "Japanese N3 Verbs",
+  "description": "…",
+  "language": "zh-TW",
+  "tags": ["japanese", "N3"],
+  "cardCount": 50,
+  "createdAt": "2026-06-14T08:00:00Z",
+  "builtBy": "memory-toast-make-card"
+}
+```
+
+## 2. cards.json schema
+
+```json
+{
+  "schemaVersion": 1,
+  "cards": [
+    {
+      "id": "<uuid>",
+      "position": 0,
+      "frontContent": "front text (may be empty, but not empty at the same time as sections)",
+      "backContent": "back text",
+      "frontSections": [
+        {
+          "id": "<uuid>",
+          "position": 0,
+          "kind": "image",            // image | audio | video
+          "storageKind": "local",     // local (file in ZIP) | external (URL)
+          "storageRef": "media/<sectionId>.jpg",  // local: path in ZIP; external: full URL
+          "caption": "caption text or null",
+          "mimeType": "image/jpeg",   // required for local; may be null for external
+          "durationMs": null          // audio/video length, may be null
+        }
+      ],
+      "backSections": []
+    }
+  ]
+}
+```
+
+Rules:
+
+- `id` is always a UUID v4; `position` starts at 0 and increments by array order.
+- For `storageKind: local`, `storageRef` must be `media/{sectionId}.{ext}` and the ZIP must
+  contain the matching file.
+- `storageKind: external` is for YouTube/Vimeo and similar links; `storageRef` is the full URL.
+- Each section needs at least one of `storageRef` / `caption` non-empty (the app's model
+  throws otherwise).
+- For each card side: the text (`frontContent`/`backContent`) and that side's sections cannot
+  both be empty.
+
+## 3. deck.json — the skill's input format
+
+`scripts/upload_pack.py` consumes a simplified format (it generates every UUID, position,
+`storageRef`, and `mimeType`). Put it in a "deck directory" with media referenced by
+relative path:
+
+```
+my-deck/
+├── deck.json
+└── assets/
+    ├── taberu.jpg          # e.g. an image you generated with gen_image.py
+    └── pronounce.mp3
+```
+
+```json
+{
+  "title": "Japanese N3 Verbs",
+  "description": "50 common verbs",
+  "language": "zh-TW",
+  "tags": ["japanese", "N3"],
+  "cards": [
+    {
+      "frontContent": "食べる",
+      "backContent": "to eat (taberu)",
+      "frontSections": [
+        { "kind": "image", "file": "assets/taberu.jpg", "caption": "optional" }
+      ],
+      "backSections": [
+        { "kind": "audio", "file": "assets/pronounce.mp3" },
+        { "kind": "video", "url": "https://www.youtube.com/watch?v=…" }
+      ]
+    }
+  ]
+}
+```
+
+- Each section must have exactly one of `file` (local → `storageKind: local`) or `url`
+  (→ `external`).
+- Extension whitelist — image: jpg/jpeg/png/gif/webp; audio: mp3/m4a/wav/aac/ogg;
+  video: mp4/mov/webm.
+- Text-only cards need just `frontContent` + `backContent`; sections may be omitted.
+- Generated images (from `gen_image.py`) are just local image sections — save them under the
+  deck directory and reference them via `file`.
+
+## 4. Upload protocol (API)
+
+`scripts/upload_pack.py` runs these steps (the same endpoints the mobile app's sync uses):
+
+| Step | Endpoint | Notes |
+|------|----------|-------|
+| 1. auth | `POST /api/v1/auth/refresh` `{refreshToken}` | mints a 15-min `accessToken`; run `mt_login.py` once to obtain the stored refresh token |
+| 2. create deck | `POST /api/v1/decks` `{title, description?, tags?}` | returns `deck.id`; skipped when updating an existing deck |
+| 3. start sync | `POST /api/v1/decks/{deckId}/sync` `{localVersion, size, sha256, cardCount}` | returns an R2 signed PUT URL (10-min) + `packId` + `r2Key` |
+| 4. upload ZIP | `PUT {uploadUrl}` (body = ZIP bytes) | query-signed URL, no extra header |
+| 5. commit | `POST /api/v1/packs/{packId}/commit` `{expectedSize, sha256, cardCount, r2Key}` | server verifies the R2 object exists and matches → writes the pack row, bumps `decks.current_pack_id` |
+
+Every request except step 4 carries `Authorization: Bearer {accessToken}`.
+
+After commit the deck appears in the app's deck list; entering it shows a "new version
+available v.N" banner with a **Download** button (the app compares the server pack version
+with the local one and offers the pull when the server is newer and no local edits are pending).
+
+## 5. Versioning & conflicts
+
+- New deck, first pack: `localVersion: 0`, which becomes version 1 after commit.
+- Updating an existing deck: `localVersion` must equal the server's current version, or sync
+  returns **409** `{error: "version_mismatch", serverVersion, localVersion}`.
+- Resolve a 409: re-run with `--local-version {serverVersion}` (confirming you want to
+  overwrite server content), or `--force` (skips the version check).
+- **Important:** an upload replaces the server pack wholesale. If the phone has un-synced local
+  edits, push them from the app first ("同步"), then update with the new version number —
+  otherwise those edits are overwritten on the next pull.
+
+## 6. Limits & validation
+
+| Item | Limit |
+|------|-------|
+| ZIP size | ≤ 100 MB |
+| title | 1–200 characters |
+| description | ≤ 1000 characters |
+| tags | ≤ 10 |
+| sha256 | 64 lowercase hex; must match the ZIP at commit |
+| expectedSize | must equal the actual R2 object size, or commit returns `size_mismatch` and the object is deleted |
+| signed PUT URL | expires in 10 minutes — upload immediately after sync |

package/scripts/_mt_auth.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Shared auth + config for the memory-toast-make-card skill.
+
+Credential store: ``~/.memory-toast/credentials.json`` (chmod 600), holding the
+rotating 7-day refresh token — never the password. Imported by ``mt_login.py``
+and ``upload_pack.py``. Zero third-party deps (Python 3.9+ stdlib only).
+"""
+
+import json
+import os
+import stat
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+DEFAULT_API_URL = "https://memory-toast-api.smallseven-87b.workers.dev"
+CONFIG_DIR = Path.home() / ".memory-toast"
+CRED_PATH = CONFIG_DIR / "credentials.json"
+# Cloudflare blocks the default Python-urllib User-Agent (error 1010).
+USER_AGENT = "memory-toast-make-card/1.0"
+
+
+def fail(msg: str) -> None:
+    print(f"ERROR: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def load_credentials() -> dict:
+    """Return the stored credentials dict, or {} if not logged in."""
+    if not CRED_PATH.is_file():
+        return {}
+    try:
+        return json.loads(CRED_PATH.read_text())
+    except json.JSONDecodeError:
+        fail(f"{CRED_PATH} is corrupted — run: python3 scripts/mt_login.py logout, then log in again")
+
+
+def save_credentials(data: dict) -> None:
+    """Write the credential store, owner read/write only (0600)."""
+    CONFIG_DIR.mkdir(mode=0o700, exist_ok=True)
+    CRED_PATH.write_text(json.dumps(data, indent=2))
+    os.chmod(CRED_PATH, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def clear_credentials() -> bool:
+    """Delete the credential store. Returns True if a file was removed."""
+    if CRED_PATH.is_file():
+        CRED_PATH.unlink()
+        return True
+    return False
+
+
+def resolve_api_url(cli_arg: str = None) -> str:
+    """Resolve the API base URL: --api flag > env > stored > built-in default."""
+    creds = load_credentials()
+    url = (cli_arg or os.environ.get("MEMORY_TOAST_API_URL")
+           or creds.get("apiUrl") or DEFAULT_API_URL)
+    return url.rstrip("/")
+
+
+def api_call(method, url, body=None, token=None, raw=None, timeout=300):
+    """Minimal JSON/binary HTTP call against the Memory Toast API.
+
+    Returns (status_code, parsed_json_or_dict). Never raises on HTTP errors.
+    """
+    headers = {"User-Agent": USER_AGENT}
+    data = None
+    if raw is not None:
+        data = raw
+        headers["Content-Type"] = "application/zip"
+    elif body is not None:
+        data = json.dumps(body).encode()
+        headers["Content-Type"] = "application/json"
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            text = resp.read().decode() or "{}"
+            return resp.status, (json.loads(text) if text.strip().startswith("{") else {})
+    except urllib.error.HTTPError as e:
+        text = e.read().decode()
+        try:
+            return e.code, json.loads(text)
+        except json.JSONDecodeError:
+            return e.code, {"raw": text}
+
+
+def login(api: str, email: str, password: str) -> dict:
+    """POST /auth/login. Returns the parsed response {user, accessToken, refreshToken}."""
+    status, res = api_call("POST", f"{api}/api/v1/auth/login",
+                           {"email": email, "password": password})
+    if status != 200:
+        msg = res.get("message") or res.get("error") or res
+        fail(f"login failed ({status}): {msg}")
+    if "refreshToken" not in res:
+        fail(f"login response missing refreshToken: {res}")
+    return res
+
+
+def get_access_token(api: str) -> str:
+    """Mint a fresh access token from the stored refresh token.
+
+    Persists the rotated refresh token (slides the 7-day idle window forward).
+    Exits with a friendly message if not logged in or the session has expired.
+    """
+    creds = load_credentials()
+    refresh = creds.get("refreshToken")
+    if not refresh:
+        fail("not logged in — run: python3 scripts/mt_login.py")
+    status, res = api_call("POST", f"{api}/api/v1/auth/refresh",
+                           {"refreshToken": refresh})
+    if status == 401:
+        fail("session expired (refresh token older than 7 days or invalid) — "
+             "run: python3 scripts/mt_login.py")
+    if status != 200 or "accessToken" not in res:
+        msg = res.get("message") or res.get("error") or res
+        fail(f"token refresh failed ({status}): {msg}")
+    # Persist the rotated refresh token; keep the stored apiUrl untouched so a
+    # one-off --api override does not clobber the user's configured server.
+    if res.get("refreshToken"):
+        creds["refreshToken"] = res["refreshToken"]
+        email = res.get("user", {}).get("email")
+        if email:
+            creds["email"] = email
+        save_credentials(creds)
+    return res["accessToken"]
+
+
+def store_refresh_token(api: str, refresh_token: str) -> str:
+    """Validate a pasted refresh token via /auth/refresh and store it.
+
+    For Google/Facebook (social-login) users who have no password: they copy this
+    token from the app (Settings → Copy upload token) and paste it here. Returns
+    the account email on success; exits with a friendly message otherwise.
+    """
+    status, res = api_call("POST", f"{api}/api/v1/auth/refresh",
+                           {"refreshToken": refresh_token})
+    if status == 401:
+        fail("that token is invalid or expired — copy a fresh one from the app "
+             "(Settings → Copy upload token)")
+    if status != 200 or "refreshToken" not in res:
+        msg = res.get("message") or res.get("error") or res
+        fail(f"token validation failed ({status}): {msg}")
+    email = res.get("user", {}).get("email", "(unknown)")
+    save_credentials({
+        "apiUrl": api,
+        "email": email,
+        "refreshToken": res["refreshToken"],  # store the freshly-rotated token
+    })
+    return email

package/scripts/gen_image.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Generate one image for a flashcard using the user's OWN OpenAI or Gemini API key.
+
+Zero third-party deps — Python 3.9+ stdlib only. The API key is read from the
+environment (or the credential store) and is never printed or stored by this script.
+
+Usage:
+  gen_image.py --provider openai|gemini --prompt "..." --out PATH
+               [--size WxH] [--model ID] [--dry-run]
+
+API key (env var, or "imageKeys" in ~/.memory-toast/credentials.json):
+  openai → OPENAI_API_KEY
+  gemini → GEMINI_API_KEY
+
+Defaults:
+  openai → gpt-image-1              (sizes: 1024x1024, 1536x1024, 1024x1536, auto)
+  gemini → imagen-4.0-generate-001  (Imagen "predict" path; pass a gemini-*-image
+           model, e.g. gemini-2.5-flash-image, to use the "generateContent" path)
+
+WARNING: this calls a PAID API billed to the user's key. The skill must confirm the
+cost with the user before generating images in bulk. Output is written as raw bytes
+(PNG by default) to --out.
+"""
+
+import argparse
+import base64
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+USER_AGENT = "memory-toast-make-card/1.0"
+GEMINI_API_VERSION = "v1beta"
+CRED_PATH = Path.home() / ".memory-toast" / "credentials.json"
+
+ENV_VAR = {"openai": "OPENAI_API_KEY", "gemini": "GEMINI_API_KEY"}
+DEFAULT_MODEL = {"openai": "gpt-image-1", "gemini": "imagen-4.0-generate-001"}
+
+
+def fail(msg: str) -> None:
+    print(f"ERROR: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def resolve_key(provider: str) -> str:
+    """Env var first, then imageKeys.<provider> in the credential store."""
+    key = os.environ.get(ENV_VAR[provider])
+    if key:
+        return key
+    try:
+        if CRED_PATH.is_file():
+            creds = json.loads(CRED_PATH.read_text())
+            return (creds.get("imageKeys") or {}).get(provider)
+    except (json.JSONDecodeError, OSError):
+        pass
+    return None
+
+
+def _http_post(url: str, payload: dict, headers: dict, timeout: int = 180):
+    data = json.dumps(payload).encode()
+    h = {"Content-Type": "application/json", "User-Agent": USER_AGENT}
+    h.update(headers)
+    req = urllib.request.Request(url, data=data, headers=h, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, json.loads(resp.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        text = e.read().decode()
+        try:
+            return e.code, json.loads(text)
+        except json.JSONDecodeError:
+            return e.code, {"raw": text}
+
+
+def _size_to_aspect(size: str):
+    """Map a WxH size to the closest Imagen aspectRatio bucket (or None)."""
+    if not size or "x" not in size.lower():
+        return None
+    try:
+        w, h = (int(x) for x in size.lower().split("x"))
+    except ValueError:
+        return None
+    if w == h:
+        return "1:1"
+    return "4:3" if w > h else "3:4"
+
+
+def gen_openai(key: str, model: str, prompt: str, size: str) -> bytes:
+    payload = {"model": model, "prompt": prompt, "n": 1, "size": size}
+    status, res = _http_post("https://api.openai.com/v1/images/generations",
+                             payload, {"Authorization": f"Bearer {key}"})
+    if status != 200:
+        fail(f"OpenAI image API error ({status}): {(res.get('error') or {}).get('message') or res}")
+    data = res.get("data") or []
+    if not data or not data[0].get("b64_json"):
+        fail(f"OpenAI returned no image data: {res}")
+    return base64.b64decode(data[0]["b64_json"])
+
+
+def gen_gemini_imagen(key: str, model: str, prompt: str, size: str) -> bytes:
+    url = f"https://generativelanguage.googleapis.com/{GEMINI_API_VERSION}/models/{model}:predict"
+    params = {"sampleCount": 1}
+    aspect = _size_to_aspect(size)
+    if aspect:
+        params["aspectRatio"] = aspect
+    payload = {"instances": [{"prompt": prompt}], "parameters": params}
+    status, res = _http_post(url, payload, {"x-goog-api-key": key})
+    if status != 200:
+        fail(f"Gemini Imagen API error ({status}): {(res.get('error') or {}).get('message') or res}")
+    preds = res.get("predictions") or []
+    for p in preds:
+        if p.get("bytesBase64Encoded"):
+            return base64.b64decode(p["bytesBase64Encoded"])
+    reasons = [p.get("raiFilteredReason") for p in preds if p.get("raiFilteredReason")]
+    fail("Gemini Imagen returned no image"
+         + (f" (filtered: {reasons})" if reasons else f": {res}"))
+
+
+def gen_gemini_content(key: str, model: str, prompt: str) -> bytes:
+    url = f"https://generativelanguage.googleapis.com/{GEMINI_API_VERSION}/models/{model}:generateContent"
+    payload = {
+        "contents": [{"parts": [{"text": prompt}]}],
+        "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]},
+    }
+    status, res = _http_post(url, payload, {"x-goog-api-key": key})
+    if status != 200:
+        fail(f"Gemini API error ({status}): {(res.get('error') or {}).get('message') or res}")
+    for cand in res.get("candidates") or []:
+        for part in (cand.get("content") or {}).get("parts") or []:
+            inline = part.get("inlineData") or part.get("inline_data") or {}
+            if inline.get("data"):
+                return base64.b64decode(inline["data"])
+    finish = (res.get("candidates") or [{}])[0].get("finishReason")
+    fail(f"Gemini returned no image (finishReason={finish}): {res}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--provider", required=True, choices=["openai", "gemini"])
+    parser.add_argument("--prompt", required=True)
+    parser.add_argument("--out", required=True, type=Path)
+    parser.add_argument("--size", default="1024x1024",
+                        help="OpenAI: literal size; Gemini Imagen: mapped to aspectRatio")
+    parser.add_argument("--model", help="override the provider's default model")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="validate args + key presence without calling the API (no cost)")
+    args = parser.parse_args()
+
+    model = args.model or DEFAULT_MODEL[args.provider]
+    key = resolve_key(args.provider)
+    if not key:
+        fail(f"missing API key — set {ENV_VAR[args.provider]} in your environment, "
+             f'or add "imageKeys": {{"{args.provider}": "..."}} to {CRED_PATH}')
+
+    if args.dry_run:
+        print(f"[dry-run] provider={args.provider} model={model} size={args.size} "
+              f"out={args.out} key=set — no API call made (no cost).")
+        return
+
+    if args.provider == "openai":
+        img = gen_openai(key, model, args.prompt, args.size)
+    elif model.startswith("imagen"):
+        img = gen_gemini_imagen(key, model, args.prompt, args.size)
+    else:
+        img = gen_gemini_content(key, model, args.prompt)
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_bytes(img)
+    print(f"Wrote {args.out} ({len(img):,} bytes) via {args.provider}/{model}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/mt_login.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Memory Toast login helper for the make-card skill.
+
+Commands:
+  login    Prompt for email + password, exchange them for a refresh token, store it.
+  token    Log in by pasting a token copied from the app — for Google/Facebook users
+           who have no password (app → Settings → Copy upload token).
+  whoami   Show the logged-in account (prints no secrets).
+  logout   Delete the stored credentials.
+
+Secrets are read interactively (never echoed) and never written to disk; only the
+rotating 7-day refresh token is stored, in ~/.memory-toast/credentials.json
+(chmod 600). Run `login` (or `token`) once, then `upload_pack.py` refreshes automatically.
+
+Examples:
+  python3 scripts/mt_login.py                 # same as `login`
+  python3 scripts/mt_login.py token           # paste a token (social-login users)
+  python3 scripts/mt_login.py whoami
+  python3 scripts/mt_login.py logout
+  python3 scripts/mt_login.py --api https://my-server.example.com login
+"""
+
+import argparse
+import getpass
+
+import _mt_auth as auth
+
+
+def cmd_login(args) -> None:
+    api = auth.resolve_api_url(args.api)
+    print(f"Memory Toast — {api}")
+    email = input("Email: ").strip()
+    if not email:
+        auth.fail("email is required")
+    password = getpass.getpass("Password: ")
+    if not password:
+        auth.fail("password is required")
+    res = auth.login(api, email, password)
+    stored_email = res.get("user", {}).get("email", email)
+    auth.save_credentials({
+        "apiUrl": api,
+        "email": stored_email,
+        "refreshToken": res["refreshToken"],
+    })
+    print(f"Logged in as {stored_email}.")
+    print(f"Credentials saved to {auth.CRED_PATH} (chmod 600). "
+          "Token stays valid as long as you upload at least once every 7 days.")
+
+
+def cmd_token(args) -> None:
+    api = auth.resolve_api_url(args.api)
+    print(f"Memory Toast — {api}")
+    token = args.token or getpass.getpass(
+        "Paste your upload token (app → Settings → Copy upload token): ")
+    token = token.strip()
+    if not token:
+        auth.fail("no token provided")
+    email = auth.store_refresh_token(api, token)
+    print(f"Logged in as {email} (via pasted token).")
+    print(f"Credentials saved to {auth.CRED_PATH} (chmod 600). "
+          "Token stays valid as long as you upload at least once every 7 days.")
+
+
+def cmd_whoami(args) -> None:
+    creds = auth.load_credentials()
+    if not creds.get("refreshToken"):
+        print("Not logged in. Run: python3 scripts/mt_login.py login")
+        return
+    print(f"Logged in as {creds.get('email', '(unknown)')}")
+    print(f"Server: {creds.get('apiUrl', auth.DEFAULT_API_URL)}")
+
+
+def cmd_logout(args) -> None:
+    if auth.clear_credentials():
+        print(f"Logged out — removed {auth.CRED_PATH}")
+    else:
+        print("Already logged out (no stored credentials).")
+
+
+def main() -> None:
+    base = argparse.ArgumentParser(add_help=False)
+    base.add_argument("--api", help="override API base URL")
+    parser = argparse.ArgumentParser(
+        description=__doc__, parents=[base],
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("login", parents=[base], help="log in and store a refresh token")
+    p_token = sub.add_parser("token", parents=[base],
+                             help="log in by pasting a token from the app (social-login users)")
+    p_token.add_argument("--token", help="the token value (omit to be prompted, hidden)")
+    sub.add_parser("whoami", parents=[base], help="show the logged-in account")
+    sub.add_parser("logout", parents=[base], help="delete stored credentials")
+    args = parser.parse_args()
+    handler = {"login": cmd_login, "token": cmd_token,
+               "whoami": cmd_whoami, "logout": cmd_logout}
+    handler[args.command or "login"](args)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/upload_pack.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Build a Memory Toast deck ZIP pack from a deck directory and upload it via the API.
+
+Zero third-party deps — Python 3.9+ stdlib only.
+
+Usage:
+  upload_pack.py DECK_DIR [--dry-run] [--deck-id ID] [--local-version N] [--force]
+                          [--api URL]
+
+DECK_DIR must contain a `deck.json` (see references/pack-format.md for the schema).
+Media files referenced by sections live anywhere under DECK_DIR (relative paths).
+
+Auth: uses the refresh token stored by `mt_login.py` — no password needed. Run
+`python3 scripts/mt_login.py` once before your first upload.
+
+Modes:
+  --dry-run          Build + validate the ZIP at DECK_DIR/build/pack.zip, no network.
+  (default)          Create a NEW deck on the server and upload the pack.
+  --deck-id ID       Upload to an EXISTING deck instead of creating one.
+                     Requires --local-version N (current server pack version) or --force.
+"""
+
+import argparse
+import hashlib
+import json
+import mimetypes
+import uuid
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from _mt_auth import api_call, fail, get_access_token, resolve_api_url
+
+MAX_ZIP_BYTES = 100 * 1024 * 1024  # server-side limit in validators/sync.ts
+
+ALLOWED_EXTS = {
+    "image": {".jpg", ".jpeg", ".png", ".gif", ".webp"},
+    "audio": {".mp3", ".m4a", ".wav", ".aac", ".ogg"},
+    "video": {".mp4", ".mov", ".webm"},
+}
+EXTRA_MIME = {
+    ".m4a": "audio/mp4",
+    ".aac": "audio/aac",
+    ".ogg": "audio/ogg",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".webp": "image/webp",
+}
+
+
+def guess_mime(ext: str) -> str:
+    if ext in EXTRA_MIME:
+        return EXTRA_MIME[ext]
+    mime, _ = mimetypes.guess_type(f"f{ext}")
+    return mime or "application/octet-stream"
+
+
+def normalize_section(sec: dict, deck_dir: Path, where: str, errors: list, media: dict) -> dict:
+    """Validate one section from deck.json and convert it to the cards.json shape.
+
+    Local files get a generated section id and a `media/{id}{ext}` storageRef;
+    the file is registered in `media` (zip path -> absolute path).
+    """
+    kind = sec.get("kind")
+    if kind not in ("image", "audio", "video"):
+        errors.append(f"{where}: kind must be image|audio|video, got {kind!r}")
+        return {}
+    sec_id = str(uuid.uuid4())
+    caption = sec.get("caption")
+    has_file = bool(sec.get("file"))
+    has_url = bool(sec.get("url"))
+    if has_file == has_url:
+        errors.append(f"{where}: exactly one of 'file' or 'url' is required")
+        return {}
+
+    if has_url:
+        url = sec["url"]
+        if not url.startswith(("http://", "https://")):
+            errors.append(f"{where}: url must be http(s), got {url!r}")
+            return {}
+        storage_kind, storage_ref, mime = "external", url, None
+    else:
+        rel = sec["file"]
+        src = (deck_dir / rel).resolve()
+        if not src.is_file():
+            errors.append(f"{where}: file not found: {rel}")
+            return {}
+        ext = src.suffix.lower()
+        if ext not in ALLOWED_EXTS[kind]:
+            errors.append(f"{where}: extension {ext!r} not allowed for kind {kind!r}")
+            return {}
+        storage_kind = "local"
+        storage_ref = f"media/{sec_id}{ext}"
+        mime = guess_mime(ext)
+        media[storage_ref] = src
+
+    return {
+        "id": sec_id,
+        "kind": kind,
+        "storageKind": storage_kind,
+        "storageRef": storage_ref,
+        "caption": caption if caption else None,
+        "mimeType": mime,
+        "durationMs": sec.get("durationMs"),
+    }
+
+
+def build_pack(deck_dir: Path) -> dict:
+    deck_json_path = deck_dir / "deck.json"
+    if not deck_json_path.is_file():
+        fail(f"missing {deck_json_path}")
+    try:
+        deck = json.loads(deck_json_path.read_text())
+    except json.JSONDecodeError as e:
+        fail(f"deck.json is not valid JSON: {e}")
+
+    errors: list = []
+    title = deck.get("title", "")
+    if not isinstance(title, str) or not (1 <= len(title) <= 200):
+        errors.append("title is required (1-200 chars)")
+    description = deck.get("description", "")
+    if len(description) > 1000:
+        errors.append("description exceeds 1000 chars")
+    tags = deck.get("tags", [])
+    if not isinstance(tags, list) or len(tags) > 10:
+        errors.append("tags must be a list of at most 10 strings")
+    cards_in = deck.get("cards")
+    if not isinstance(cards_in, list) or not cards_in:
+        fail("deck.json must contain a non-empty 'cards' array")
+
+    media: dict = {}
+    cards_out = []
+    for i, card in enumerate(cards_in):
+        where = f"cards[{i}]"
+        front = card.get("frontContent", "")
+        back = card.get("backContent", "")
+        if not isinstance(front, str) or not isinstance(back, str):
+            errors.append(f"{where}: frontContent/backContent must be strings")
+            continue
+        front_secs, back_secs = [], []
+        for side, key, out in (("front", "frontSections", front_secs), ("back", "backSections", back_secs)):
+            for j, sec in enumerate(card.get(key) or []):
+                norm = normalize_section(sec, deck_dir, f"{where}.{key}[{j}]", errors, media)
+                if norm:
+                    norm["position"] = len(out)
+                    out.append(norm)
+        if not front and not front_secs:
+            errors.append(f"{where}: card front is empty (no text, no sections)")
+        if not back and not back_secs:
+            errors.append(f"{where}: card back is empty (no text, no sections)")
+        cards_out.append({
+            "id": str(uuid.uuid4()),
+            "position": i,
+            "frontContent": front,
+            "backContent": back,
+            "frontSections": front_secs,
+            "backSections": back_secs,
+        })
+
+    if errors:
+        fail("deck.json validation failed:\n  - " + "\n  - ".join(errors))
+
+    manifest = {
+        "schemaVersion": 1,
+        "deckTitle": title,
+        "description": description,
+        "language": deck.get("language", "zh-TW"),
+        "tags": tags,
+        "cardCount": len(cards_out),
+        "createdAt": datetime.now(timezone.utc).isoformat(),
+        "builtBy": "memory-toast-make-card",
+    }
+
+    build_dir = deck_dir / "build"
+    build_dir.mkdir(exist_ok=True)
+    zip_path = build_dir / "pack.zip"
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2))
+        zf.writestr("cards.json", json.dumps({"schemaVersion": 1, "cards": cards_out}, ensure_ascii=False, indent=2))
+        for zip_name, src in media.items():
+            zf.write(src, zip_name)
+
+    data = zip_path.read_bytes()
+    if len(data) > MAX_ZIP_BYTES:
+        fail(f"ZIP is {len(data)} bytes — exceeds the 100MB server limit")
+    return {
+        "zip_path": zip_path,
+        "size": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+        "card_count": len(cards_out),
+        "media_count": len(media),
+        "title": title,
+        "description": description,
+        "tags": tags,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("deck_dir", type=Path)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--deck-id", help="upload to an existing deck instead of creating one")
+    parser.add_argument("--local-version", type=int, default=0,
+                        help="current server pack version of the deck (for --deck-id updates)")
+    parser.add_argument("--force", action="store_true", help="overwrite server pack on version conflict")
+    parser.add_argument("--api", help="override API base URL")
+    args = parser.parse_args()
+
+    deck_dir = args.deck_dir.resolve()
+    if not deck_dir.is_dir():
+        fail(f"deck dir not found: {deck_dir}")
+
+    pack = build_pack(deck_dir)
+    print(f"Built {pack['zip_path']}")
+    print(f"  cards: {pack['card_count']}  media: {pack['media_count']}  "
+          f"size: {pack['size']:,} bytes  sha256: {pack['sha256']}")
+    if args.dry_run:
+        print("Dry run — not uploading.")
+        return
+
+    api = resolve_api_url(args.api)
+    token = get_access_token(api)
+    print(f"Authenticated to {api}")
+
+    if args.deck_id:
+        deck_id = args.deck_id
+    else:
+        body = {"title": pack["title"]}
+        if pack["description"]:
+            body["description"] = pack["description"]
+        if pack["tags"]:
+            body["tags"] = pack["tags"]
+        status, res = api_call("POST", f"{api}/api/v1/decks", body, token)
+        if status != 201:
+            fail(f"create deck failed ({status}): {res}")
+        deck_id = res["deck"]["id"]
+        print(f"Created deck {deck_id} ({pack['title']})")
+
+    sync_url = f"{api}/api/v1/decks/{deck_id}/sync"
+    if args.force:
+        sync_url += "?force=true"
+    status, res = api_call("POST", sync_url, {
+        "localVersion": args.local_version,
+        "size": pack["size"],
+        "sha256": pack["sha256"],
+        "cardCount": pack["card_count"],
+    }, token)
+    if status == 409:
+        fail(
+            f"version conflict: server is at version {res.get('serverVersion')}, "
+            f"you sent {res.get('localVersion')}.\n"
+            f"Re-run with --local-version {res.get('serverVersion')} (or --force to overwrite)."
+        )
+    if status != 200:
+        fail(f"sync start failed ({status}): {res}")
+    upload_url, pack_id, r2_key = res["uploadUrl"], res["packId"], res["r2Key"]
+
+    print(f"Uploading {pack['size']:,} bytes to R2…")
+    status, res = api_call("PUT", upload_url, raw=pack["zip_path"].read_bytes())
+    if status not in (200, 201):
+        fail(f"R2 upload failed ({status}): {res}")
+
+    status, res = api_call("POST", f"{api}/api/v1/packs/{pack_id}/commit", {
+        "expectedSize": pack["size"],
+        "sha256": pack["sha256"],
+        "cardCount": pack["card_count"],
+        "r2Key": r2_key,
+    }, token)
+    if status != 200:
+        fail(f"commit failed ({status}): {res}")
+
+    version = res.get("pack", {}).get("version")
+    print(f"Done. deck={deck_id} pack={pack_id} version={version}")
+    print("Open the app deck list and pull the deck to see it on device.")
+
+
+if __name__ == "__main__":
+    main()