@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/reference/client-guide.md

@@ -0,0 +1,180 @@
+# Hướng dẫn MÁY KHÁCH — dùng skill game-art qua node trong LAN
+
+Dành cho máy **không** có tài khoản sinh ảnh / GPU, muốn mượn của một hay nhiều **node**
+trong mạng. Máy khách chạy skill y như bình thường; chỉ việc sinh ảnh và các bước cần GPU là
+gửi sang node. Mọi thứ còn lại chạy tại chỗ.
+
+Bạn chỉ cần hai thứ từ người quản lý node: **địa chỉ node** và **token**. Không cần biết node
+được dựng thế nào.
+
+---
+
+## 0. Máy khách cần gì
+
+| | Máy khách |
+|---|---|
+| Cookie Gemini / tài khoản sinh ảnh | ❌ không cần |
+| torch / GPU (~2GB) | ❌ không cần |
+| Chạy skill (dò màu, tách nền, chấm điểm, ghi file) | ✅ tại chỗ |
+| Địa chỉ node + token | ✅ do người quản lý node cấp |
+
+Bản máy khách chỉ gồm thư mục **`client/`** (+ `SKILL.md` + `reference/`). Không cần thư mục
+`server/` (code node) hay `models/` (trọng số).
+
+---
+
+## 1. Cài đặt (3 bước)
+
+**a. Lấy BẢN MÁY KHÁCH.** Trên máy có bản skill gốc, chạy:
+
+```bash
+python server/pack.py
+```
+
+Tạo **`game-art-client.zip`** (+ `game-art-node.zip` cho node). Chép file `.zip` sang máy khách,
+giải nén ra:
+
+```
+game-art-client/
+  SKILL.md
+  reference/
+  client/           <- code máy khách (gemini_image_mcp.py, imglib.py, lớp mượn-node…)
+```
+
+Bản này **không có** file node, không trọng số model, **không token**. Máy khách **không cần**
+bản skill gốc — thư mục này tự đủ.
+
+> Chỉ cần một THƯ MỤC (không nén) thì `python server/make_client_bundle.py` → `game-art-client/`.
+
+**b. Cài gói cho máy khách** — bản nhẹ, KHÔNG có torch:
+
+```bash
+pip install -r client/requirements-client.txt
+```
+
+Gồm: `mcp`, `pillow`, `numpy<2`, `curl_cffi`, `httpx`. (Không cần `torch`/`ben2`/`opencv` — model
+chạy trên node.)
+
+**c. Đăng ký MCP** (một lần) — trỏ vào MCP entry trong `client/`:
+
+```bash
+claude mcp add --scope user gemini-image -- python "<đường dẫn>/client/gemini_image_mcp.py"
+```
+
+Rồi **restart Claude Code**. Kiểm bằng `claude mcp get gemini-image` — thấy đường dẫn đúng
+là được.
+
+> Tự kiểm bản client lành lặn (không bắt buộc): `cd client && python test_imglib.py` (in
+> `112/112 passed`) và `python test_restyle_tools.py` (`0 failed`).
+
+---
+
+## 2. Cấu hình `.env`
+
+Chép `client/.env.example` thành **`client/.env`**, rồi sửa 2 dòng:
+
+```ini
+GAMEART_REMOTE_NODES=http://192.168.0.131:8765/mcp,http://192.168.0.132:8765/mcp
+GAMEART_REMOTE_TOKEN=<token do người quản lý node cấp>
+```
+
+- **Địa chỉ node và token** do người quản lý node đưa cho bạn.
+- **Nhiều node** thì ngăn bằng dấu phẩy — client tự chọn node rảnh, tự đổi khi bận/hết quota.
+- **Token riêng cho từng node** (nếu được cấp): `http://192.168.0.132:8765/mcp|token-rieng`.
+- Chỉ cần 2 dòng trên; các dòng khác trong `.env.example` bỏ trống được.
+
+Vài điều dễ vấp:
+
+- File phải tên đúng `.env`, đặt **trong `client/`** (cạnh `gemini_image_mcp.py`). Trỏ chỗ khác
+  bằng env `GAMEART_ENV_FILE`.
+- Biến môi trường THẬT thắng file `.env`. Nên nếu đăng ký MCP có `-e GAMEART_REMOTE_TOKEN=...`
+  thì nó đè file — nhớ để tránh sửa file mà không thấy tác dụng.
+- `.env` đã được `.gitignore`, **đừng commit** (có token trong đó). File `.env.example` KHÔNG
+  được chứa token thật.
+
+---
+
+## 3. Kiểm tra trước khi chạy
+
+Gọi hai tool này (không tốn lượt sinh ảnh):
+
+**`auth_status()`** — ở chế độ mượn node trả `mode: "remote"`, cờ khả năng là của **cả cụm**:
+
+```json
+{"mode":"remote","logged_in":true,"codex":true,"ben2":true,"esrgan":true,
+ "n_nodes":2,"n_alive":2}
+```
+
+- `logged_in:true` = sinh ảnh Gemini đang sẵn sàng; `codex/ben2/esrgan` tương tự cho từng khả năng.
+- `n_alive` < `n_nodes` = có node không gọi tới được (xem `remote_nodes()`).
+
+**`remote_nodes()`** — cho biết `.env` đã nạp chưa và từng node có gọi tới được không:
+
+```json
+{"enabled":true,
+ "env":{"loaded_from":".../client/.env",
+        "searched":[".../client/.env",".../game-art/.env"],
+        "keys":["GAMEART_REMOTE_NODES","GAMEART_REMOTE_TOKEN"]},
+ "nodes":[{"url":"http://192.168.0.131:8765/mcp","ok":true,"name":"gpu-01",
+           "available":{"gemini":true,"codex":true,"ben2":true,"esrgan":true}},
+          {"url":"http://192.168.0.130:8765/mcp","ok":false,
+           "error":"ConnectError: All connection attempts failed"}]}
+```
+
+- `enabled:false` → chưa đọc được `.env`. Xem `env.loaded_from`: `null` nghĩa là không tìm
+  thấy file. `searched` liệt kê nơi đã tìm; `keys` cho biết biến nào đã có (chỉ TÊN, không lộ
+  giá trị token).
+- `ok:true` trên một node = **client đã kết nối tới node đó**.
+- `ok:false` kèm `error` → node đó không gọi tới được (thường do sai địa chỉ, sai token, hoặc
+  node chưa sẵn sàng — báo người quản lý node).
+- `available` là các khả năng node đó đang nhận. Khả năng nào `false` thì client không gửi
+  loại việc đó tới node đó (nó tự chọn node khác).
+
+---
+
+## 4. Dùng hằng ngày — KHÔNG có gì đổi
+
+Quy trình restyle/thumbnail/screen-sheet **y hệt** bản chạy local. Bạn không phải gọi tool
+mới hay thêm cờ. Khác biệt duy nhất: lúc sinh ảnh và chạy model, việc được gửi sang node.
+
+- `restyle_asset` và `process_raws` trả thêm field `remote` (tóm tắt cụm: `n_alive`, các cờ
+  khả năng). Chi tiết hơn thì gọi `remote_nodes()`.
+- Sinh ảnh Codex chạy như cũ — máy khách **không cần** `codex` CLI, nó tự gửi sang node.
+
+**Khi mọi node bận**: client chờ tối đa **15 phút** (đổi bằng `GAMEART_REMOTE_WAIT`, giây),
+tự thử lại khi có node rảnh. Quá hạn thì báo lỗi kèm lý do — lúc đó mới cần bạn xử lý
+(thêm node vào `.env`, hay đợi quota hồi).
+
+**Node tắt giữa chừng** không làm hỏng pipeline: các bước cần model có thể thiếu, nhưng cách
+tách nền theo màu + phóng to bằng LANCZOS vẫn chạy đủ để ra asset. Chỉ **sinh ảnh** là bắt
+buộc phải có node (máy khách không tự sinh được).
+
+---
+
+## 5. Khắc phục sự cố (phía máy khách)
+
+| Triệu chứng | Nguyên nhân | Xử |
+|---|---|---|
+| `auth_status` trả `mode: "remote"` nhưng `enabled` ở `remote_nodes` là `false` | `.env` chưa được đọc | kiểm `env.loaded_from` trong `remote_nodes()`; file phải tên `.env` trong `client/` |
+| tạo `.env` rồi mà không thấy tác dụng | đặt sai chỗ, hoặc env hệ thống đang đè | `remote_nodes().env.loaded_from` chỉ ra file đang dùng; xoá biến trùng trong env phiên |
+| node báo `ok:false`, error `ConnectError` | sai địa chỉ, hoặc node chưa sẵn sàng | so lại địa chỉ trong `.env` với địa chỉ được cấp; nếu vẫn lỗi thì báo người quản lý node |
+| `từ chối token (401)` | token trong `.env` không khớp | so lại token với token được cấp; phân biệt hoa thường |
+| `node từ chối header Host (421)` | node chưa cho phép địa chỉ bạn đang gọi | báo người quản lý node — cần cấu hình phía node |
+| `mọi node bận/không dùng được ... sau 15 phút` | cả cụm kẹt hoặc hết quota | `remote_nodes()` xem node nào bận/hết quota; thêm node vào `.env` hoặc nâng `GAMEART_REMOTE_WAIT` |
+| một node không bao giờ được chọn | `available` của nó `false` cho khả năng cần | node đó tạm không nhận loại việc này; đợi hoặc báo người quản lý node |
+| asset ra mềm/nhoè | bản sinh nhỏ hơn khung mà không node nào phóng nét được | kiểm `available.esrgan` trong `remote_nodes()`; hoặc sinh nguồn to hơn |
+
+---
+
+## 6. Tóm tắt biến môi trường của máy khách
+
+| Biến | Bắt buộc | Ý nghĩa |
+|---|---|---|
+| `GAMEART_REMOTE_NODES` | ✅ (hoặc `_URL`) | danh sách node, ngăn bằng phẩy; mỗi mục `url` hoặc `url\|token` |
+| `GAMEART_REMOTE_TOKEN` | ✅ | token mặc định cho node không khai riêng |
+| `GAMEART_REMOTE_URL` | — | một node duy nhất (tương thích bản cũ) |
+| `GAMEART_REMOTE_WAIT` | — | chờ tối đa khi mọi node bận (giây, mặc định 900) |
+| `GAMEART_ENV_FILE` | — | trỏ file `.env` ở chỗ khác |
+
+Không đặt biến nào → skill chạy **thuần local** (cần torch + tài khoản sinh ảnh trên chính
+máy này). Đặt `GAMEART_REMOTE_NODES` là bật chế độ mượn node.

package/plugins/phaser-casual-game-factory/skills/game-art/reference/mcp-image-input.md

@@ -0,0 +1,148 @@
+# MCP gemini-image — ảnh đầu vào & bảo trì
+
+## Tool surface
+
+Server self-contained — chứa cả logic tách nền (`imglib.py`). 5 tool:
+
+```
+generate_image(prompt, image_paths=None, out_dir=None) -> str          # sinh ảnh thô (KHÔNG tách nền)
+plan_asset(src, avoid=None) -> dict                                     # size/bbox/palette/key/key_safe
+restyle_asset(prompt, image_paths, src=None, key=None,
+              size=None, n=3, out_dir=None) -> dict                     # sinh N + tách nền + bám size
+make_contact_sheet(labels, images, out, cell=160) -> dict              # sheet 3 nền để duyệt mắt
+apply_asset(variant, dst, backup_dir, project_root=None) -> dict        # backup rồi ghi đè bản gốc
+```
+
+- `image_paths`: tối đa 4 ảnh (.png/.jpg/.jpeg/.webp, <=7MB) mỗi lượt.
+- `generate_image` trả **chuỗi** `"Saved:\n<abs path>..."` hoặc `"Error: <Type>: <msg>"` — **không
+  raise**, phải kiểm tiền tố `Error:`.
+- 4 tool restyle trả **dict**; hỏng thì trả `{"error": "..."}` — **không raise**, phải kiểm field
+  `error`. Chi tiết field (`variants[]`, `flags`, `key_safe`, an toàn `apply_asset`…) xem `SKILL.md`.
+- Trong prompt, chỉ ảnh bằng **"the FIRST image" / "the SECOND image"** theo đúng thứ tự `image_paths`.
+
+## Server nằm trong skill
+
+Server là một phần của skill này: thư mục **`server/`** (cạnh `SKILL.md`) chứa
+`gemini_image_mcp.py` + `imglib.py` + `requirements.txt` + test. MCP được đăng ký chạy thẳng từ
+đó — skill tự chứa, không phụ thuộc thư mục ngoài nào.
+
+Cài trên máy mới: sau khi có skill, `pip install -r server/requirements.txt`
+(`mcp`, `curl_cffi`, `pillow`, `numpy`), rồi
+`claude mcp add --scope user gemini-image --env "GEMINI_1PSID=..." --env "GEMINI_1PSIDTS=..." -- python "<.../skills/restyle-asset/client/gemini_image_mcp.py>"`.
+`imglib.py` phải nằm CÙNG thư mục với `gemini_image_mcp.py` (server `import imglib`).
+
+## Cách nó hoạt động
+
+1. `POST https://content-push.googleapis.com/upload/` — header `push-id: feeds/mcudyrk2a4khkz`,
+   multipart `file`. Body trả về = `file_id` (dạng `/contrib_service/ttl_1d/<hash>`).
+2. `file_id` được nhét vào payload `f.req` tại `message_content[3]`:
+   `[[[file_id, 1], filename], ...]`
+
+**curl_cffi KHÔNG hỗ trợ `files=` / `data=` kiểu requests/httpx.** Truyền vào là nó ném
+`NotImplementedError: files is not supported, use multipart`. Phải dựng `CurlMime`:
+
+```python
+from curl_cffi import CurlMime
+
+mime = CurlMime()
+mime.addpart(name="file", content_type="image/png", filename=path.name, data=blob)
+mime.addpart(name="File name", data=path.name.encode("utf-8"))
+r = await session.post(_UPLOAD_URL, headers={"push-id": _UPLOAD_PUSH_ID}, multipart=mime)
+mime.close()
+```
+
+Đã verify bằng lần gọi thật: upload trả về `file_id` hợp lệ.
+
+## Cảnh báo bảo mật
+
+`generate_image` giờ **đọc và ghi file cục bộ**. Bản gốc cố ý không có bề mặt file.
+→ **Chỉ chạy stdio local. Không bao giờ tunnel/expose server này ra mạng.**
+
+## __Secure-1PSIDTS XOAY VÒNG — lý do session "tự nhiên chết"
+
+Đây là bug đã sửa, ghi lại vì nó cực dễ chẩn đoán nhầm.
+
+`__Secure-1PSIDTS` **xoay vòng liên tục** — Google trả giá trị mới qua `Set-Cookie` sau vài
+request, và giá trị **cũ chết ngay**. Bản gốc của MCP nạp cookie từ env mỗi lần gọi rồi **vứt bỏ**
+cookie mới Google vừa set. Nên chỉ cần Google xoay một nhịp là session rơi về **đăng xuất** —
+đo được: cookie tươi dùng được đúng vài phút / vài lượt sinh rồi chết.
+
+Đã vá: `_save_psidts()` bắt lấy giá trị mới sau mỗi lần `_auth`, ghi xuống
+`~/.cache/gemini_mcp/psidts` (đổi được bằng `GEMINI_PSIDTS_CACHE`). `_load_psidts()` ưu tiên
+cache hơn env — env giờ chỉ là **hạt giống ban đầu**.
+
+Kèm theo: `_auth()` giờ **bắt trạng thái đăng xuất và báo thẳng**. Trước đó nó im lặng đi tiếp và
+lỗi hiện ra là `No image URL in response` — câu đó khiến người ta đi sửa nhầm `_IMAGE_MODEL_ID`
+hoặc prompt, trong khi thủ phạm chỉ là cookie chết.
+
+**Vì sao bẫy này khó thấy:** Gemini **vẫn chat bình thường khi đăng xuất** (chat ẩn danh được
+phép) — nên session "trông như còn sống". Chỉ **tạo ảnh** mới bắt buộc đăng nhập.
+
+## Cookie hết hạn — nguyên nhân #1 khi lỗi
+
+Triệu chứng **rõ ràng**: `Error: RuntimeError: Redirected to consent page` hoặc
+`Could not find any auth token`.
+
+Triệu chứng **âm thầm, dễ chẩn đoán nhầm** (gặp thật rồi):
+`Error: RuntimeError: No image URL in response...` — và nếu bạn dump body ra thì thấy Gemini
+trả lời bằng CHỮ: *"I can try to find an image like that for you, but can't create it right now.
+It's possible you're signed out..."*
+
+Đừng đi sửa `_IMAGE_MODEL_ID` hay prompt — **chat ẩn danh vẫn chạy, chỉ tạo ảnh mới bắt buộc
+đăng nhập.** Cookie hết hạn thì Google serve bản logged-out: chat trả lời bình thường (dễ tưởng
+là ổn), nhưng mọi yêu cầu tạo ảnh đều bị từ chối.
+
+Cách kiểm trong 5 giây — GET `/app` rồi soi HTML:
+
+```python
+html = (await session.get(f"{_BASE}{_INIT_PATH}")).text
+print("token at (SNlM0e):", bool(_TOKEN_RE["at"].search(html).group(1)))  # RỖNG = đăng xuất
+print("co link dang nhap:", "accounts.google.com/ServiceLogin" in html)   # True = đăng xuất
+```
+
+`at` rỗng **và** có link đăng nhập → cookie chết, làm mới theo dưới đây.
+
+### Cách lấy lại — TỰ ĐỘNG qua Chrome + CDP (mặc định, không copy tay)
+
+Không còn phải copy cookie trong DevTools rồi đăng ký lại MCP. Cơ chế hiện tại:
+
+- **Profile Chrome cố định** `~/.cache/gemini_mcp/chrome_debug_profile`, mở kèm
+  `--remote-debugging-port=9222`. Profile riêng nên KHÔNG đụng cửa sổ Chrome thường của user.
+- `server/refresh_gemini_cookies.py` nối CDP, ghé `RotateCookiesPage`, trích cookie, ghi
+  `~/.cache/gemini_mcp/cookies.txt` (đường dẫn theo env `GEMINI_COOKIES_FILE`).
+- `gemini_image_mcp.py` **tự gọi script đó** khi bắt được `_LoggedOut` giữa lúc gen ảnh
+  (`_refresh_cookies_via_brave`, tắt bằng `GEMINI_AUTO_REFRESH=0`), có backup file cookie cũ
+  và cooldown `GEMINI_REFRESH_COOLDOWN` để một lô n=3 cookie chết không refresh 3 lần.
+
+Việc duy nhất cần con người: **đăng nhập lần đầu** (và khi Google thu hồi hẳn session):
+
+```bash
+python server/refresh_gemini_cookies.py --login    # mở cửa sổ profile cố định -> đăng nhập Gemini
+python server/refresh_gemini_cookies.py            # trích cookie + tự verify
+python server/refresh_gemini_cookies.py --status   # chỉ kiểm còn sống không
+```
+
+Để cửa sổ debug đó **mở sẵn** thì refresh sau này không phải bật lại Chrome.
+
+### Bẫy chết người: phải lấy cookie ĐÚNG SCOPE gemini.google.com
+
+Triệu chứng: script báo `Da ghi 30 cookie (ho can: ... =co)` — **đủ tên cookie** — nhưng bước
+verify vẫn `[THAT BAI] Cookie da ghi NHUNG Google tu choi`, và profile trong Chrome thì rõ ràng
+vẫn đăng nhập. Rất dễ kết luận nhầm là "Google đã bind/DBSC, hết cứu".
+
+Thủ phạm: `Network.getAllCookies` trả về **mọi** cookie trong profile, gồm loại chỉ thuộc
+`accounts.google.com` — `__Host-1PLSID`, `__Host-3PLSID`, `__Host-GAPS`, `__Host-GAPSTS`,
+`LSID`, `SMSV`, `ACCOUNT_CHOOSER`. Cookie tiền tố `__Host-` vốn **host-only**; nhồi chúng vào
+header gửi `gemini.google.com` là sai scope và Google **loại cả bộ**.
+
+Đúng: `Network.getCookies(urls=["https://gemini.google.com/app", ...])` — CDP chỉ trả tập cookie
+trình duyệt THỰC SỰ gửi kèm request tới origin đó (đo được: 22 cookie thay vì 30, và dùng được
+ngay). `_extract()` làm đúng vậy; nhánh dự phòng quét cả profile vẫn phải lọc `__Host-*` +
+`_ACCOUNTS_ONLY`.
+
+`__Secure-1PSIDTS` xoay vòng vài ngày một lần — đây là cái hết hạn trước.
+
+## Khi protocol Google đổi
+
+Mọi hằng số dễ vỡ nằm gọn trong khối `# PROTOCOL` đầu `gemini_image_mcp.py`:
+endpoint, `push-id`, model id, regex URL ảnh. Sinh ảnh hỏng mà cookie vẫn tốt → sửa ở đó.

package/plugins/phaser-casual-game-factory/skills/game-art/reference/prompt-template.md

@@ -0,0 +1,216 @@
+# Prompt template
+
+Prompt dưới đây **dùng chung nguyên văn cho cả HAI backend**: Gemini web qua MCP
+(`generate_image`, danh sách ảnh = `image_paths`) và `codex_gen.sh` (danh sách ảnh = các
+`--ref` theo thứ tự). "The FIRST image" luôn là phần tử đầu của danh sách đó.
+
+(Antigravity CLI `agy` / Nano Banana đã bị TẮT khỏi luồng — đừng thêm lại.)
+
+## Anchor pass — asset đầu tiên (chưa có anchor)
+
+`image_paths = [<asset gốc>, <ref1>, <ref2>, <ref3>]` (tối đa 3 ref — giới hạn 4 ảnh
+đầu vào tổng cộng áp cho mọi backend, xem `reference/mcp-image-input.md`)
+
+```
+Redraw the subject from the FIRST image. Keep its exact shape, silhouette,
+proportions and orientation — do not add or remove any part.
+
+{SHAPE_LOCK}
+
+Restyle it as: {STYLE_BLOCK}
+
+{IF_REFS}Match the art style, palette, lighting and rendering of the other
+reference images exactly.{/IF_REFS}
+
+Output: a single subject on a perfectly flat solid {KEY_HEX} background. The background is
+an exact uniform digital color fill — every background pixel exactly {KEY_HEX}, like a
+chroma-key screen — NOT a photographed studio backdrop; no vignette, no lighting falloff on
+the background. Draw the subject SMALL and centered so it fills only the middle ~60% of the
+image, with a WIDE empty margin of background on all four sides AND in all four corners —
+the subject must stay well clear of every edge and every corner. No cast shadow on the
+background. No gradient. No text. No watermark. No border.
+Do NOT use {KEY_HEX} or ANY shade of that hue anywhere inside the artwork itself — not for
+outlines, strokes, line art, shading, rims or details. The subject's own colors must stay
+clearly away from that hue.
+```
+
+## Batch pass — đã có golden anchor
+
+`image_paths = [<asset gốc>, <styles/<ten>.anchor.png>]`
+
+```
+Redraw the subject from the FIRST image. Keep its exact shape, silhouette,
+proportions and orientation — do not add or remove any part.
+
+{SHAPE_LOCK}
+
+Match the art style, palette, material, lighting and rendering of the SECOND
+image exactly. The SECOND image is the reference for style only — do NOT copy
+its subject.
+
+Output: a single subject on a perfectly flat solid {KEY_HEX} background. The background is
+an exact uniform digital color fill — every background pixel exactly {KEY_HEX}, like a
+chroma-key screen — NOT a photographed studio backdrop; no vignette, no lighting falloff on
+the background. Draw the subject SMALL and centered so it fills only the middle ~60% of the
+image, with a WIDE empty margin of background on all four sides AND in all four corners —
+the subject must stay well clear of every edge and every corner. No cast shadow on the
+background. No gradient. No text. No watermark. No border.
+Do NOT use {KEY_HEX} or ANY shade of that hue anywhere inside the artwork itself — not for
+outlines, strokes, line art, shading, rims or details. The subject's own colors must stay
+clearly away from that hue.
+```
+
+## Screen sheet — reskin cả màn hình (chế độ riêng, xem SKILL.md § Chế độ Screen Sheet)
+
+`danh sách ảnh vào = [<screenshot màn hình>]` (+ tối đa 2 ref style nếu có — vẫn giới hạn 4 ảnh)
+
+```
+Redesign the game screen from the FIRST image in this style: {STYLE_BLOCK}
+
+Compose ONE single image with exactly TWO stacked sections:
+
+TOP HALF — the full redesigned screen mockup: keep the SAME layout, the SAME UI elements
+at the SAME positions and proportions as the FIRST image. Only the art style changes.
+
+BOTTOM HALF — a sprite-sheet strip on a perfectly flat solid {KEY_HEX} background. Redraw
+each of these UI elements from the mockup separately: {ELEMENT_LIST}. Space them WELL
+APART — never touching each other, never touching the image edges. The background of this
+bottom section is an exact uniform digital color fill — every background pixel exactly
+{KEY_HEX}, like a chroma-key screen — NOT a photographed studio backdrop; no vignette.
+
+No text labels, no annotations, no arrows, no grid lines, no borders between elements.
+No watermark.
+```
+
+- `{ELEMENT_LIST}` = danh sách chi tiết muốn cắt, **liệt kê tường minh và ĐẾM**
+  ("the round play button, the coin icon, the settings gear, the top score panel — exactly
+  4 elements"). Nhìn screenshot rồi liệt kê — model bám danh sách đếm được tốt hơn hẳn
+  "all UI elements" (cùng bài học với {SHAPE_LOCK}).
+- Mockup ở nửa trên KHÔNG cần nền key — nó được giữ nguyên làm ảnh duyệt tổng thể, chỉ
+  dải dưới cần key để `slice_sheet` cắt.
+- Model hay vẽ ranh giới hai vùng lệch khỏi đúng 50% — nhìn sheet thật rồi chỉnh
+  `mockup_frac` khi gọi `slice_sheet`, đừng tin con số mù quáng.
+
+## Thumbnail cửa hàng — 3 tỉ lệ (chế độ riêng, xem SKILL.md § Chế độ Thumbnail)
+
+`danh sách ảnh vào = [<screenshot Home>, <asset chính>, <asset phụ>, <ref style>]` — **tối đa 4
+ảnh**, nên phải CHỌN. Screenshot Home luôn là ảnh đầu; nếu user đưa nhiều asset hơn 3 thì lấy
+những cái xuất hiện to nhất trong thumb và **nói rõ cái nào bị bỏ**.
+
+Chạy **3 lượt riêng, mỗi tỉ lệ một lượt** — đừng cố cắt 3 size từ một ảnh: cắt 16:9 xuống 5:7
+là mất 60% khung, chủ thể sẽ bị chặt. Chỉ đổi khối `{ORIENTATION}`, phần còn lại giữ nguyên văn:
+
+```
+Create a promotional thumbnail for this mobile game, in {ORIENTATION}.
+
+The FIRST image is a screenshot of the game's Home screen — use it as the source of truth for
+the game's subject matter, characters and world. The other images are the game's own assets:
+feature them as the hero elements of the thumbnail.
+
+Art style: {STYLE_BLOCK}
+
+Composition: ONE clear focal subject, large and centered, instantly readable at small size.
+Rich but uncluttered background that supports the subject. Strong colour contrast and clear
+silhouette so it stands out in a crowded store grid. Dramatic lighting.
+
+Keep ALL important content inside the central safe area — leave a generous margin on every
+edge, because the image will be cropped slightly to an exact aspect ratio.
+
+No text, no logo, no title, no words, no letters, no numbers, no UI buttons, no watermark,
+no borders, no frames, no drop-shadow panels.
+```
+
+`{ORIENTATION}` — dùng ĐÚNG một trong ba, đo thật thấy model tôn trọng hướng:
+
+| Tỉ lệ | `{ORIENTATION}` | Gemini trả về | Sau `make_thumbs` |
+|---|---|---|---|
+| 1:1 | `a perfect SQUARE 1:1 aspect ratio` | 1024×1024 | 1024×1024 (cắt 0%) |
+| 5:7 | `TALL PORTRAIT orientation, 5:7 aspect ratio (taller than wide)` | 864×1216 | 540×756 (cắt 0.49%) |
+| 16:9 | `WIDE LANDSCAPE orientation, 16:9 aspect ratio` | 1376×768 | 1280×720 (cắt 0.80%) |
+
+Vì sao có từng dòng:
+
+| Dòng | Chặn lỗi gì |
+|---|---|
+| `No text, no logo, no title, no words, no letters, no numbers` | Model sinh ảnh **viết chữ sai chính tả/méo** gần như luôn luôn. Thumb có chữ rác là không dùng được, mà sửa thì phải sinh lại cả ảnh. Để trống rồi **chèn logo thật bằng công cụ khác** — đó là cách duy nhất chắc chắn. Liệt kê nhiều từ đồng nghĩa vì cấm mỗi `No text` thì model vẫn vẽ số/nhãn. |
+| `Keep ALL important content inside the central safe area` | `make_thumbs` phải cắt bù 0.5–0.8% để về đúng tỉ lệ. Nhỏ, nhưng chủ thể chạm sát mép thì vẫn bị liếm mất. |
+| `instantly readable at small size` | Thumb hiển thị thật ở cỡ ~100–200px trong lưới cửa hàng. Không có dòng này model vẽ chi tiết li ti, thu nhỏ ra một đống bùn. |
+| `The FIRST image is a screenshot ... source of truth` | Không nói rõ thì model coi screenshot là **ảnh cần restyle** và trả về một cái màn hình game khác, không phải poster. |
+| Chạy 3 lượt riêng thay vì cắt 1 ảnh | 16:9 → 5:7 mất ~60% khung. Sinh riêng thì mỗi tỉ lệ có bố cục đúng cho khung đó. |
+
+## Vì sao có từng dòng negative
+
+| Dòng | Chặn lỗi gì |
+|---|---|
+| `exact uniform digital color fill ... NOT a photographed studio backdrop` | Model ảnh (đo thật trên Nano Banana và Gemini web) hay hiểu "solid background" thành **phông studio chụp thật** — ra "xanh studio" `#2ED246` kèm vignette thay vì `#00FF00` → chroma-key trượt CẢ khung (`bad_background`, coverage=1.0) dù bản sinh đẹp. Dòng này ép nền là màu số tuyệt đối. Tool còn lưới đỡ **auto-key** (tự dò màu nền thật từ vành ảnh khi key yêu cầu trượt cả khung — `key_auto: true` trong variant), nhưng prompt đúng thì đỡ phải cứu. |
+| `No cast shadow on the background` | Bóng đổ làm nền **không phẳng** → chroma key để lại vệt bẩn (`bad_background`). Lỗi hay gặp nhất. |
+| `No gradient` | Nền gradient → khoảng cách tới màu key biến thiên → alpha lỗ chỗ (`bad_background`). |
+| `No text` / `No watermark` | Model ảnh hay tự thêm nhãn/chữ vào tranh. |
+| `Do NOT use {KEY_HEX} or ANY shade of that hue inside the artwork` | **Đo thật, ca đã gặp:** yêu cầu nền `#00FF00`, model vẽ bánh răng bạc nhưng lấy **xanh lá ĐẬM `(19,78,27)` làm nét viền** — cùng hue với key (129° vs 120°) nhưng tối hơn nên cách `#00FF00` tới 362 đơn vị. Kết quả: asset có viền xanh đậm sai hẳn style, và **tách nền KHÔNG cứu được** — thử xoá theo hue thì gặm mép thành rỗ như mối ăn (vì không phân biệt được "nét vẽ" với "nền sót" bằng màu). Phải chặn từ prompt. |
+| Nền model vẽ **KHÔNG bao giờ đúng `{KEY_HEX}`** | Đo thật: yêu cầu `#00FF00` → model vẽ `#0CF508` và `#0BD009` (G=209!). Không phải lỗi prompt, và không cần sửa prompt: pipeline đã **đo màu nền thật** rồi key theo màu đó (xem `bg_color_used` / `bg_sampled` trong variant). Cứ giữ `{KEY_HEX}` trong prompt để model vẽ nền PHẲNG một màu — đó mới là thứ prompt cần đảm bảo. |
+| `No border` | Khung viền dính vào bbox → asset bị thu nhỏ sai. |
+| `do NOT copy its subject` | Không có dòng này, model hay vẽ luôn con mèo trong ảnh anchor. |
+| `Leave a clear margin ... must NOT touch the image edge` | `border_impurity` (trong `restyle_asset`) kiểm nền bằng cách đo **vành ngoài 4px** của ảnh thô — nó GIẢ ĐỊNH vành đó là nền thuần. Chủ thể chạm mép → vành ngoài lẫn màu chủ thể → báo nhầm `bad_background`, tốn một lượt sinh lại. Đây là đánh đổi cố ý (thà báo nhầm còn hơn để lọt một asset hỏng), nên dòng prompt này là cách DUY NHẤT để tránh false positive, không phải văn phong tuỳ chọn — bắt buộc phải có. |
+| Khối `{SHAPE_LOCK}` — ràng buộc **đếm được** | Gemini bám style rất tốt nhưng **bám hình dạng thì lỏng**. Ca thật, đã đo: icon bánh răng **6 răng** ra thành **8 và 12 răng**, có bản còn tự thêm vòng đồng tâm — dù prompt ĐÃ có sẵn câu `keep its exact shape`. Câu đó **một mình vô dụng**. Thêm ràng buộc ĐẾM ĐƯỢC thì sửa được ngay: `EXACTLY 6 rounded teeth. Not 8. Not 12. Six.` + `ONE plain central hole, no concentric rings` → **3/3 bản ra đúng 6 răng**. Phải đếm hộ model. |
+
+## Watermark ✦ của Gemini — đã xoá TỰ ĐỘNG, chính xác
+
+Prompt KHÔNG cấm được con dấu này: Google đóng nó bất kể bạn viết gì (`No watermark` trong
+prompt là để chặn model tự VẼ nhãn, không liên quan tới dấu ✦ hệ thống).
+
+**Nó là gì, đo thật:** một ngôi sao 4 cánh **TRẮNG THUẦN, alpha CỐ ĐỊNH**, phủ vào ô **48x48 px
+cách cạnh phải và cạnh dưới đúng 96 px**. Hiệu chuẩn bằng 3 ảnh nền-đen sinh riêng: hình học
+trùng khít từng pixel (828 pixel sáng, đỉnh 78/255 → α ≈ 0.305), ba kênh RGB lệch nhau đúng
+`0.0`. Đo lại trên canvas 1024x1024: vẫn 48x48 @ 96px — **hình học không scale theo cạnh ảnh**.
+
+Điều đó giải thích con số cũ ghi trong tài liệu này ("chấm xanh `(81,249,77)`"): đó KHÔNG phải
+màu của watermark mà là watermark trắng **đã trộn lên nền xanh key**. Giải ngược
+`(81,249,77)` ra nền gốc `≈(5,246,0)` — đúng một màu "xanh studio" model hay vẽ.
+
+**Vì alpha cố định, phép trộn ĐẢO ĐƯỢC**: `S = (O - 255α)/(1-α)`. Nên `imglib.unwatermark_gemini`
+lấy lại ĐÚNG pixel gốc, không inpaint/blur đoán. Sai số chỉ do lượng tử hoá, khuếch đại
+`1/(1-α) ≈ 1.44` lần → tối đa **~1 mức**, đo được trên mọi nền thử.
+
+**Chạy ở đâu:** ngay khi ảnh tải về, TRƯỚC mọi thao tác khác (`_strip_wm` trong
+`gemini_image_mcp.py`), và ở đầu `process_raws` + `slice_sheet` cho ảnh backend ngoài. Phải sớm
+như vậy vì watermark nằm trong pixel màu: tách nền/cắt sheet/resize đều bôi nó ra hoặc bake vào
+asset, và sau khi ảnh bị resize thì hình học 48x48@96px không còn đúng nên **không còn cách nào
+lấy lại pixel gốc**. Tắt bằng `GEMINI_KEEP_WATERMARK=1` (chỉ để chẩn đoán).
+
+Với ảnh nguồn LẪN (`process_raws`, `slice_sheet`) hàm chạy `verify=True`: chỉ đảo khi đo được
+bằng chứng, vì đảo bừa lên ảnh Codex/GPT Image 2 sạch sẽ ĐÓNG một ngôi sao TỐI vào đó. Báo về
+qua `watermark_removed` trong kết quả.
+
+**Vẫn giữ dòng "middle ~60% + WIDE margin + empty corners"** trong prompt — không còn vì
+watermark nữa, mà để phục vụ `border_impurity` và tránh chủ thể chạm mép.
+
+`postprocess` vẫn còn 2 lớp cũ (`despeckle` → `strip_gemini_watermark`) chạy SAU tách nền, giờ
+chỉ là lưới an toàn cho trường hợp Google đổi hình học. Bình thường chúng không còn việc gì:
+**`speckles_removed: 0` giờ mới là bình thường**, vì watermark đã bị xoá từ trước.
+
+## Điền {STYLE_BLOCK} và {KEY_HEX}
+
+- `{STYLE_BLOCK}` = mục "Mô tả một câu" trong `tools/restyle/styles/<ten>.md` (xem SKILL.md bước 1).
+- `{KEY_HEX}` = field `key` trả về từ tool `plan_asset(<asset>)` — **không tự bịa màu key**,
+  vì `plan` đã chọn màu xa nhất mọi màu trong asset gốc (tránh ăn thủng chủ thể).
+- `{IF_REFS}...{/IF_REFS}` chỉ giữ đoạn bên trong khi thực sự có ảnh tham chiếu phong cách
+  ngoài asset gốc (anchor pass, có ref ngoài); bỏ hẳn đoạn này ở batch pass vì lúc đó câu
+  "match the SECOND image" đã làm việc đó rồi.
+
+## {SHAPE_LOCK} — BẮT BUỘC, không phải tuỳ chọn
+
+`keep its exact shape` **một mình không giữ được hình dạng.** Đã đo: bánh răng 6 răng ra 8 và 12
+răng dù prompt có sẵn câu đó. Trước mỗi lần sinh, **nhìn asset gốc và đếm**, rồi viết ra:
+
+```
+Look at the FIRST image. It is a {MÔ TẢ NGẮN}. Reproduce that EXACT silhouette:
+- EXACTLY {N} {bộ phận}. Not {N-2}. Not {N+2}. {N}.
+- {ràng buộc hình học khác: 'ONE plain central hole, no concentric rings, no spokes'}
+- Same proportions, same orientation.
+If you overlaid your result on the FIRST image, the two outlines must line up.
+Only the MATERIAL and RENDERING change — not the shape.
+```
+
+Chủ thể **không có bộ phận đếm được** (một con mèo, một đám mây) thì thay bằng ràng buộc hình
+học cụ thể nhất có thể ("một tai nhọn hai bên, đuôi cong sang PHẢI, không thêm phụ kiện").
+Càng cụ thể, silhouette càng khớp.