memory-toast-make-card 0.1.0 → 0.6.0

package/README.md

@@ -1,5 +1,8 @@
 # memory-toast-make-card
 
+[![npm](https://img.shields.io/npm/v/memory-toast-make-card)](https://www.npmjs.com/package/memory-toast-make-card)
+[![license: MIT](https://img.shields.io/npm/l/memory-toast-make-card)](LICENSE)
+
 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**,
@@ -62,6 +65,9 @@ You can also drive the scripts directly:
 ```bash
 S=~/.claude/skills/memory-toast-make-card/scripts
 
+# One-time: choose where decks are kept (remembered; keeps them out of /tmp)
+python3 $S/mt_config.py set deck-root ~/Documents/MemoryToast/decks
+
 # 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" \
@@ -70,16 +76,57 @@ python3 $S/gen_image.py --provider openai \
 # 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
+# Create a new deck and upload (writes my-deck/.memory-toast.json)
+python3 $S/upload_pack.py my-deck
+
+# Update the SAME deck later — just run it again; it auto-reads the record
 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>
+# Publish to the public Library, then release new versions later
+python3 $S/library_pack.py publish my-deck --category language --description "..."
+python3 $S/library_pack.py release my-deck --changelog "Added 10 cards"
 ```
 
 See [`references/pack-format.md`](references/pack-format.md) for the `deck.json` schema, the
 upload protocol, limits, and version/conflict rules.
 
+### Deck storage, updates & publishing
+
+- Decks are built under a **remembered root** (`mt_config.py set deck-root <path>`), not /tmp,
+  so the editable source survives reboots. Each deck folder gets a `.memory-toast.json` record
+  (deckId, version, structure, …) on upload — the state a later session reads to continue.
+- To **update** a deck, edit it and re-run `upload_pack.py <deck-dir>`; it reads that record and
+  bumps the server version automatically — no ids to remember (`--new` forces a fresh deck).
+- To **share** a deck, `library_pack.py publish` it to the public Library (categories: language,
+  science, history, programming, math, geography, exam, other), then `release` new versions as
+  you update it. `status` lists what you've published.
+
+## Rich text in cards
+
+A card's `frontContent` / `backContent` (and a section's `caption`) may contain a small **HTML
+subset** for formatting; plain text is always valid, so existing decks keep working unchanged.
+`make-card` emits this HTML straight from `deck.json` — what you write is what the app renders.
+
+Allowed tags:
+
+- `<b>` / `<strong>` — bold
+- `<i>` / `<em>` — italic
+- `<u>` — underline
+- `<br>` — line break
+- `<span style="font-size:sm|base|lg|xl;color:<token>">` — inline size and/or color
+- `<p style="text-align:left|center|right">…</p>` — paragraph alignment
+
+Font sizes are four semantic levels — `sm`, `base`, `lg`, `xl` (not arbitrary px). Color tokens
+are: `primary`, `red`, `orange`, `green`, `blue`, `purple`, `gray`.
+
+```json
+{ "frontContent": "<b>紅蘋果</b>", "backContent": "apple <span style=\"font-size:lg;color:red\">(fruit)</span>" }
+```
+
+Anything outside the whitelist (other tags, attributes, styles, or color values) is dropped
+while its text is kept — no scripts ever run. See
+[`references/pack-format.md`](references/pack-format.md) §3.1 for the full rules.
+
 ## Configuration
 
 - **Server URL** resolves as: `--api` flag → `MEMORY_TOAST_API_URL` env → stored value →

package/SKILL.md

@@ -37,6 +37,21 @@ Ask (in the user's language) only what is missing, one item at a time:
 - Whether cards should have **generated images** — and if so, the visual style
   (e.g. flat vector icon, watercolor, photoreal) and which provider (OpenAI / Gemini).
 
+**Deck storage location (do this first — never build decks in /tmp):**
+
+```bash
+python3 scripts/mt_config.py get deck-root      # prints the saved root, or empty
+```
+
+If empty, ask the user where to keep their decks, then save it (remembered across sessions in
+`~/.memory-toast/config.json`):
+
+```bash
+python3 scripts/mt_config.py set deck-root ~/Documents/MemoryToast/decks
+```
+
+Build each deck at `<deck-root>/<slug>/` — `mt_config.py path <slug>` prints the full path.
+
 ### 2. Collect data
 
 - **User files:** read PDFs/images directly and transcribe (a dedicated `pdf` skill is
@@ -80,9 +95,18 @@ self-explanatory play button. Use a caption only when it carries real informatio
 
 ### 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:
+Create the deck directory at `<deck-root>/<slug>/` (the root from step 1 — **never /tmp**,
+which is wiped on reboot and loses the editable source + AI record). Put `deck.json` (schema
+in pack-format.md §3) and any `assets/` there. Do NOT hand-write UUIDs, positions,
+`storageRef`, or `mimeType` — the script generates them. On upload the script also writes
+`.memory-toast.json` (the AI record) into this directory.
+
+Rich text is supported: `frontContent` / `backContent` / `caption` may use an HTML subset
+for font size, bold/italic/underline, color, and paragraph alignment. The script emits the
+matching `*Html` keys automatically and falls back to plain text for old-style content. See
+the whitelist + examples in pack-format.md §3.1 — stay inside it or tags are stripped.
+
+Then:
 
 ```bash
 python3 scripts/upload_pack.py <deck-dir> --dry-run
@@ -93,20 +117,45 @@ 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)
+# New deck (creates it, uploads pack v1, writes .memory-toast.json)
 python3 scripts/upload_pack.py <deck-dir>
 
-# Update an existing deck — needs the current server version
+# Update the SAME deck later — just run it again. upload_pack.py reads
+# .memory-toast.json and auto-updates (deckId + version); no flags needed.
+python3 scripts/upload_pack.py <deck-dir>
+
+# Override target/version explicitly if needed (--new forces a brand-new deck):
 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.
+Every successful upload (re)writes the deck's `.memory-toast.json` — the **AI record** a
+future session reads to update or publish the deck. 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
+### 7. Publish to the Library (optional)
+
+Decks are private until published. To share a deck publicly, use `scripts/library_pack.py`
+(reads `deckId` from `.memory-toast.json`):
+
+```bash
+# Publish once (category: language|science|history|programming|math|geography|exam|other)
+python3 scripts/library_pack.py publish <deck-dir> \
+  --category language --description "..." --learning-language es
+
+# After updating the deck (upload_pack.py first), push a new public version:
+python3 scripts/library_pack.py release <deck-dir> --changelog "Added digraphs"
+
+python3 scripts/library_pack.py status          # list your published packs
+```
+
+`publish` records the `libraryPackId` back into `.memory-toast.json`, so `release` later needs
+no ids. Confirm with the user before publishing — it makes the deck publicly downloadable.
+
+### 8. 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" →

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.6.0",
+  "description": "Claude Code skill to build Memory Toast flashcard decks (卡包) — with optional AI image generation using your own OpenAI/Gemini key — and upload, update, or publish them to your Memory Toast account.",
   "bin": {
     "memory-toast-make-card": "bin/install.js"
   },

package/references/pack-format.md

@@ -73,7 +73,7 @@ pack.zip
 
 Rules:
 
-- `id` is always a UUID v4; `position` starts at 0 and increments by array order.
+- `id` is a UUID v4. **On re-upload of the same deck, `upload_pack.py` matches each card against the previous build (`build/pack.zip`) by content and reuses the existing id for unchanged cards** (including back-only edits, e.g. adding an example) — only new cards or cards whose front text changed get a fresh UUID. This keeps the user's study progress across deck updates (the app keys study progress by card id and prunes orphaned progress on pull). `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.
@@ -126,6 +126,108 @@ my-deck/
 - Generated images (from `gen_image.py`) are just local image sections — save them under the
   deck directory and reference them via `file`.
 
+### 3.1 Rich text — the HTML subset
+
+`frontContent` / `backContent` and a section's `caption` may be **HTML-subset** strings that
+carry **font size, bold / italic / underline, color, and paragraph alignment**. The mobile app
+parses them with the same whitelist; anything outside it is dropped (tag removed, inner text
+kept), so as long as you stay inside the whitelist, what you emit is what the app renders.
+
+Whitelist (identical to `apps/mobile/.../rich_text/rich_html_parser.dart`):
+
+| Class | Allowed | Meaning |
+|-------|---------|---------|
+| inline | `<b>` `<strong>` | bold |
+| inline | `<i>` `<em>` | italic |
+| inline | `<u>` | underline |
+| inline | `<br>` | line break |
+| inline | `<span style="…">` | **only** `font-size:sm\|base\|lg\|xl` and/or `color:<token>` |
+| block  | `<p style="text-align:left\|center\|right">…</p>` | paragraph alignment |
+
+- `color` token must be one of: `primary` `red` `orange` `green` `blue` `purple` `gray`.
+- Any other tag (`<div>`, `<script>`, …), other attribute (`class`, `onclick`, …), or other
+  style prop/value (`font-weight`, `99px`, `hotpink`, …) is dropped while its text is kept.
+
+How the emitter derives `*Html` + plain text:
+
+- The rich source for a field is the explicit `frontContentHtml` / `backContentHtml` /
+  `captionHtml` key on the card/section if present; otherwise the `frontContent` /
+  `backContent` / `caption` value itself if it contains whitelist tags.
+- With a rich source: the output `*Html` = sanitized whitelist HTML, and the plain field =
+  the tag-stripped text (used for search + as a render fallback).
+- With no rich source: only the plain field is emitted; the `*Html` key is **omitted** so
+  old-style plain packs stay byte-clean.
+- The empty-card check (front/back + sections not all empty) runs against the **plain** text.
+
+Rich card in deck.json (the two forms are equivalent — use either):
+
+```json
+{
+  "frontContent": "<b>食べる</b><br><span style=\"font-size:lg;color:red\">godan verb</span>",
+  "backContent": "to eat (taberu)"
+}
+```
+
+```json
+{
+  "frontContent": "食べる",
+  "frontContentHtml": "<b>食べる</b><br><span style=\"font-size:lg;color:red\">godan verb</span>",
+  "backContent": "to eat (taberu)"
+}
+```
+
+Both produce, in `cards.json`:
+`frontContentHtml = "<b>食べる</b><br><span style=\"font-size:lg;color:red\">godan verb</span>"`
+and `frontContent = "食べる\ngodan verb"` (the plain projection).
+
+### 3.2 Ordered blocks — advanced layout
+
+Most cards only need `frontContent` + `frontSections[]`. To control the **exact vertical
+order** (e.g. "word → audio right under it → KK/POS → a tappable example → image"), a card
+side may instead use `frontBlocks` / `backBlocks`: an **ordered** array of blocks. The app
+renders blocks in order when present; cards without blocks render via `*Content` +
+`*Sections` exactly as before.
+
+Block types:
+
+| type | fields | notes |
+|------|--------|-------|
+| `text` | `content` / `contentHtml` (rich, §3.1 whitelist), `audios[]` (optional), `audioAlign` / `audioSize` (optional) | a text run; may carry a row of tap-to-play audio buttons below it |
+| `image` | `file` (local) or `url` (external), `caption` / `captionHtml` (optional) | image, same rules as a §3 image section |
+
+Each `audios[]` button: `{ "label": "US", "file": "assets/x.us.mp3" }` (or `url`); `label`
+may be rich (`labelHtml`). Each button is independently tap-to-play — no autoplay, no toggle;
+add more buttons for more accents.
+
+The audio row's layout is tunable per text block: `audioAlign` = `start` / `center` (default) /
+`end` (horizontal alignment of the button row), and `audioSize` = `sm` / `md` (default) / `lg`
+(button padding, icon and label size). Older app versions ignore these and use the defaults.
+
+deck.json example (back uses blocks; front stays a plain word):
+
+```json
+{
+  "frontContent": "<p style=\"text-align:center\"><b><span style=\"font-size:xl\">apple</span></b></p>",
+  "backBlocks": [
+    { "type": "text", "content": "<b><span style=\"font-size:xl\">apple</span></b>",
+      "audios": [ {"label":"US","file":"assets/apple.us.mp3"}, {"label":"UK","file":"assets/apple.uk.mp3"} ],
+      "audioAlign": "center", "audioSize": "md" },
+    { "type": "text", "content": "<span style=\"color:gray\">[ˈæpl̩]</span><br><b><span style=\"color:primary\">n.</span></b> apple" },
+    { "type": "text", "content": "<b>e.g.</b> I eat an <b>apple</b>.",
+      "audios": [ {"label":"US","file":"assets/apple.ex1.us.mp3"}, {"label":"UK","file":"assets/apple.ex1.uk.mp3"} ] },
+    { "type": "image", "file": "assets/apple.webp" }
+  ]
+}
+```
+
+**Backward compatibility (important):** when emitting blocks, `upload_pack.py` ALSO writes an
+equivalent legacy projection — `backContent` (text blocks joined) + `backSections` (image
+blocks and every audio turned into a section, caption = the button's label). So new app
+versions render the new layout from `*Blocks`, while old app versions ignore `*Blocks` and
+render the previous layout from `*Content` + `*Sections`. `schemaVersion` stays `1` (purely
+additive optional keys). Each block's media follows the same extension whitelist and gets
+generated UUID/position/storageRef/mimeType, just like §3 sections.
+
 ## 4. Upload protocol (API)
 
 `scripts/upload_pack.py` runs these steps (the same endpoints the mobile app's sync uses):
@@ -159,7 +261,7 @@ with the local one and offers the pull when the server is newer and no local edi
 
 | Item | Limit |
 |------|-------|
-| ZIP size | ≤ 100 MB |
+| ZIP size | ≤ 300 MB |
 | title | 1–200 characters |
 | description | ≤ 1000 characters |
 | tags | ≤ 10 |

package/scripts/gen_image.py

@@ -74,6 +74,13 @@ def _http_post(url: str, payload: dict, headers: dict, timeout: int = 180):
             return e.code, {"raw": text}
 
 
+def _http_get_bytes(url: str, timeout: int = 120) -> bytes:
+    """Download raw bytes (used for DALL·E URL responses)."""
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read()
+
+
 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():
@@ -88,15 +95,19 @@ def _size_to_aspect(size: str):
 
 
 def gen_openai(key: str, model: str, prompt: str, size: str) -> bytes:
+    # No response_format param: gpt-image-1 returns base64 (and rejects the param),
+    # while DALL·E returns a URL — handle whichever comes back.
     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"])
+    if data and data[0].get("b64_json"):
+        return base64.b64decode(data[0]["b64_json"])
+    if data and data[0].get("url"):
+        return _http_get_bytes(data[0]["url"])
+    fail(f"OpenAI returned no image data: {res}")
 
 
 def gen_gemini_imagen(key: str, model: str, prompt: str, size: str) -> bytes:

package/scripts/library_pack.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Publish a Memory Toast deck to the public Library, or release a new version.
+
+Reads the deck's .memory-toast.json (written by upload_pack.py) for deckId and
+libraryPackId, so you just point it at the same deck directory. Auth uses the
+refresh token stored by mt_login.py — no password. Zero deps (Python 3.9+ stdlib).
+
+CLI:
+  library_pack.py publish DECK_DIR --description TEXT --category CAT
+                  [--title T] [--language zh-TW] [--learning-language es]
+                  [--tags a,b,c] [--api URL]
+  library_pack.py release DECK_DIR [--changelog TEXT] [--api URL]
+  library_pack.py status  [--api URL]
+
+Categories (key): language science history programming math geography exam other
+
+publish  → makes the deck's current pack public as a NEW library pack (once).
+release  → publishes the deck's CURRENT pack as a NEW library version. Push the
+           new deck content with upload_pack.py FIRST, then release.
+status   → lists your published library packs.
+"""
+
+import argparse
+from pathlib import Path
+
+from _mt_auth import api_call, fail, get_access_token, load_credentials, resolve_api_url
+from upload_pack import DECK_RECORD, read_record, write_record
+
+CATEGORIES = ["language", "science", "history", "programming", "math", "geography", "exam", "other"]
+
+
+def _deck_id_from_record(deck_dir: Path):
+    record = read_record(deck_dir)
+    deck_id = record.get("deckId")
+    if not deck_id:
+        fail(f"no deckId in {deck_dir / DECK_RECORD} — run upload_pack.py first to upload the deck")
+    return deck_id, record
+
+
+def cmd_publish(args) -> None:
+    deck_dir = args.deck_dir.resolve()
+    deck_id, record = _deck_id_from_record(deck_dir)
+    api = resolve_api_url(args.api)
+    token = get_access_token(api)
+
+    body = {
+        "deckId": deck_id,
+        "title": (args.title or record.get("title") or "")[:100],
+        "description": args.description,
+        "category": args.category,
+        "language": args.language or record.get("language") or "zh-TW",
+    }
+    if args.learning_language:
+        body["learningLanguage"] = args.learning_language
+    if args.tags:
+        body["tags"] = [t.strip() for t in args.tags.split(",") if t.strip()][:10]
+
+    status, res = api_call("POST", f"{api}/api/v1/library/publish", body, token)
+    if status == 409:
+        lp_id = (res.get("libraryPack") or {}).get("id")
+        if lp_id:
+            write_record(deck_dir, {"libraryPackId": lp_id})
+        fail(f"already published as libraryPack {lp_id} — use `release` to push a new version.")
+    if status != 201:
+        fail(f"publish failed ({status}): {res}")
+    lp = res["libraryPack"]
+    write_record(deck_dir, {"libraryPackId": lp["id"]})
+    print(f"Published. libraryPack={lp['id']} category={args.category}")
+    print(f"Recorded libraryPackId in {DECK_RECORD}. The deck is now public in the Library.")
+
+
+def cmd_release(args) -> None:
+    deck_dir = args.deck_dir.resolve()
+    deck_id, record = _deck_id_from_record(deck_dir)
+    lp_id = record.get("libraryPackId")
+    if not lp_id:
+        fail(f"no libraryPackId in {DECK_RECORD} — run `library_pack.py publish` first")
+    api = resolve_api_url(args.api)
+    token = get_access_token(api)
+
+    body = {"deckId": deck_id}
+    if args.changelog:
+        body["changelog"] = args.changelog
+    status, res = api_call("POST", f"{api}/api/v1/library/packs/{lp_id}/release", body, token)
+    if status != 201:
+        fail(f"release failed ({status}): {res}")
+    ver = (res.get("pack") or {}).get("version")
+    print(f"Released new library version v{ver} for libraryPack={lp_id}.")
+
+
+def cmd_status(args) -> None:
+    api = resolve_api_url(args.api)
+    token = get_access_token(api)
+    status, res = api_call("GET", f"{api}/api/v1/library/my-published", token=token)
+    if status != 200:
+        fail(f"status failed ({status}): {res}")
+    packs = res.get("packs", [])
+    who = load_credentials().get("email", "you")
+    print(f"{who} has {len(packs)} published library pack(s):")
+    for p in packs:
+        ver = p.get("latestVersion") or p.get("version")
+        print(f"  - {p.get('title')}  id={p.get('id')}  category={p.get('category')}  v{ver}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--api", help="override API base URL")
+
+    pub = sub.add_parser("publish", parents=[common], help="publish the deck to the Library (once)")
+    pub.add_argument("deck_dir", type=Path)
+    pub.add_argument("--description", required=True, help="1-500 chars, shown in the Library")
+    pub.add_argument("--category", required=True, choices=CATEGORIES)
+    pub.add_argument("--title", help="default: title from .memory-toast.json (max 100)")
+    pub.add_argument("--language", help="content language (default: deck language)")
+    pub.add_argument("--learning-language", help="language being learned, e.g. es / ja")
+    pub.add_argument("--tags", help="comma-separated, max 10")
+    pub.set_defaults(func=cmd_publish)
+
+    rel = sub.add_parser("release", parents=[common], help="release a new version of a published deck")
+    rel.add_argument("deck_dir", type=Path)
+    rel.add_argument("--changelog", help="1-500 chars describing what changed")
+    rel.set_defaults(func=cmd_release)
+
+    st = sub.add_parser("status", parents=[common], help="list your published library packs")
+    st.set_defaults(func=cmd_status)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/mt_config.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Persistent config for make-card — remembered across sessions.
+
+Stored at ~/.memory-toast/config.json (chmod 600), shared by every make-card
+script. Zero deps — Python 3.9+ stdlib only.
+
+The main use is `deckRoot`: the folder where deck directories live so they are
+NOT built in /tmp (which is wiped on reboot). Each deck is a subfolder
+`<deckRoot>/<slug>/` holding deck.json, assets, build/, and .memory-toast.json.
+
+CLI:
+  mt_config.py show                       # print the whole config
+  mt_config.py get deck-root              # print deckRoot (empty line if unset)
+  mt_config.py set deck-root ~/Decks      # set + persist deckRoot (expands ~)
+  mt_config.py path <slug>                # print <deckRoot>/<slug> (errors if unset)
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".memory-toast"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+# CLI keys (kebab) -> JSON keys (camel)
+_KEY_MAP = {"deck-root": "deckRoot"}
+
+
+def load_config() -> dict:
+    if CONFIG_PATH.is_file():
+        try:
+            return json.loads(CONFIG_PATH.read_text() or "{}")
+        except json.JSONDecodeError:
+            return {}
+    return {}
+
+
+def save_config(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg, ensure_ascii=False, indent=2) + "\n")
+    try:
+        os.chmod(CONFIG_PATH, 0o600)
+    except OSError:
+        pass
+
+
+def get_deck_root():
+    """Return the configured deck root as a string, or None if unset."""
+    return load_config().get("deckRoot")
+
+
+def set_deck_root(path: str) -> Path:
+    resolved = Path(path).expanduser().resolve()
+    cfg = load_config()
+    cfg["deckRoot"] = str(resolved)
+    save_config(cfg)
+    return resolved
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("show")
+    g = sub.add_parser("get")
+    g.add_argument("key", choices=list(_KEY_MAP))
+    s = sub.add_parser("set")
+    s.add_argument("key", choices=list(_KEY_MAP))
+    s.add_argument("value")
+    p = sub.add_parser("path")
+    p.add_argument("slug")
+    args = parser.parse_args()
+
+    if args.cmd == "show":
+        print(json.dumps(load_config(), ensure_ascii=False, indent=2))
+    elif args.cmd == "get":
+        print(load_config().get(_KEY_MAP[args.key], ""))
+    elif args.cmd == "set":
+        if args.key == "deck-root":
+            resolved = set_deck_root(args.value)
+            print(f"deckRoot = {resolved}")
+    elif args.cmd == "path":
+        root = get_deck_root()
+        if not root:
+            print("ERROR: deckRoot is unset — run: mt_config.py set deck-root <path>",
+                  file=sys.stderr)
+            sys.exit(1)
+        print(str(Path(root) / args.slug))
+
+
+if __name__ == "__main__":
+    main()