@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/SKILL.md

@@ -0,0 +1,846 @@
+---
+name: game-art
+description: Use when re-styling existing game art assets — generating a new art style for PNG assets while keeping their exact shape, using Gemini web via MCP and/or Codex CLI (GPT Image 2) — whichever backends are alive; one backend is enough, always deliver compare.html demo — then removing the background (runs SEVERAL cutout methods per image — algebraic unmix, chroma-key on the measured background colour, chroma-key on the requested key, BEN2 — scores each on measurable criteria and delivers the best one) and outputting at the original asset's exact size (upscaling with Real-ESRGAN x4plus_anime_6B when the generated image is smaller than the target - again scoring several methods and picking the best), with a self-contained web page to review variants. Also has a Thumbnail mode - generate store thumbnails at exactly 1:1 (min 512x512), 5:7 (540x756) and 16:9 (min 1280x720) from a style + Home screenshot + game assets, no background removal. And a Screen Sheet mode - reskin a WHOLE game screen from a screenshot - one generated image = full restyled mockup on top + key-background detail strip below, sliced into individual assets. Triggers on "đổi style asset", "restyle asset", "game art", "làm lại asset theo phong cách", "re-skin game art", "tạo asset mới từ asset cũ", "generate asset from existing asset", "review asset trên web", "reskin màn hình", "reskin cả màn hình từ screenshot", "screen sheet", "tạo thumb game", "làm thumbnail game", "ảnh quảng bá game", "game thumbnail".
+---
+
+# game-art — Restyle Asset
+
+Sinh asset game mới **từ asset có sẵn**: giữ nguyên hình dạng, đổi phong cách, tách nền,
+xuất ra **đúng size + đúng vị trí của asset gốc** để thay 1-1 mà không phải sửa code layout.
+
+**Sinh ảnh dùng Gemini web (MCP) và/hoặc Codex `codex` (GPT Image 2)** — xem mục
+"Sinh ảnh — backend". **Không bắt buộc so sánh chéo hai AI.** Còn **ít nhất 1 backend** là
+đủ để gen + luôn xuất `compare.html` demo. Cả hai sống thì có thể chạy cả hai (tuỳ chọn,
+không bắt buộc). Tách nền, bám size, duyệt sheet và apply vẫn chạy trên MCP `gemini-image` —
+**12 tool, không còn script rời nào trong project** (script sinh ảnh Codex nằm trong
+`server/` của skill, không phải trong project). Ngoài luồng theo-asset mặc định còn hai chế độ
+riêng, xem mục riêng bên dưới: **Screen Sheet** (reskin CẢ màn hình từ screenshot) và
+**Thumbnail** (3 tỉ lệ cửa hàng):
+
+> **BẮT BUỘC — kết thúc MỖI lượt thiết kế bằng một file HTML đối chiếu.** Xong bất kỳ lượt
+> sinh nào (anchor pass, batch pass, screen sheet, thumbnail, hay chỉ sinh lại 1 asset) thì CUỐI
+> CÙNG luôn là `make_compare_sheet` → `compare.html`, rồi **đưa đường dẫn file đó cho user**.
+> Chỉ cần **≥1 biến thể** từ backend còn sống — **vẫn phải** dựng `compare.html` (đối chiếu
+> gốc ↔ bản mới). Không kết luận "xong" khi chưa có file này. Không tự chọn hộ bản nào.
+
+| Tool | Việc |
+|---|---|
+| `plan_asset(src, avoid)` | Đọc asset gốc → size, bbox, palette, **màu key an toàn** (`key`, `key_safe`) |
+| `process_raws(raws, src, key, size, out_dir, prefix, full_bleed)` | **Tách nền + bám size gốc** cho ảnh THÔ sinh từ Gemini/`codex` — nửa postprocess của `restyle_asset` tách riêng, trả cùng cấu trúc `variants[]`. **Đường mặc định** |
+| `slice_sheet(sheet, key, out_dir, prefix, mockup_frac)` | **Chế độ Screen Sheet**: mổ ảnh "mockup màn hình + dải chi tiết" thành `<prefix>_mockup.png` (giữ nguyên) + từng cell tự dò, tách nền, đánh số theo thứ tự đọc |
+| `restyle_asset(prompt, image_paths, src, key, size, n, out_dir, full_bleed)` | Sinh N biến thể qua **Gemini web (cookie)** + tách nền + bám size gốc (gộp generate + postprocess). Gọn khi CHỈ dùng Gemini (vd thiếu Codex CLI) — đổi lại tên ra `v<i>.png`, không mang nhãn backend |
+| `make_thumbs(sources, out_dir, anchor, prefix)` | **Chế độ Thumbnail**: cắt bù + resize ảnh thô về ĐÚNG 3 size cửa hàng (1:1 1024², 5:7 540×756, 16:9 1280×720). KHÔNG tách nền |
+| `remote_nodes()` | **Chế độ mượn máy**: bảng TẢI + QUOTA của mọi node trong LAN, và vì sao node nào được chọn. Không tốn lượt sinh ảnh |
+| `upscale_image(image_paths, out_dir, size, scale, prefix)` | **Phóng to** ảnh đã có (Real-ESRGAN x4plus_anime_6B) khi bản sinh nhỏ hơn size cần — cũng chạy nhiều cách rồi chấm điểm chọn. Các tool trên đã tự gọi khi cần; tool này để dùng tay |
+| `make_compare_sheet(groups, out, cell)` | Dựng **trang ĐỐI CHIẾU compare.html tự chứa** — gom nhóm theo asset, bản gốc cạnh biến thể, **nhấn giữ để lật về gốc ngay tại chỗ**. **BẢN GIAO BẮT BUỘC sau mỗi lượt thiết kế** |
+| `make_web_sheet(labels, images, out, cell)` | Dựng trang review.html lưới phẳng (mọi ảnh ngang hàng, không nhóm, không lật gốc). Dùng khi chỉ cần soi mép cutout mà KHÔNG cần đối chiếu gốc |
+| `make_contact_sheet(labels, images, out, cell)` | Dựng sheet PNG 3 nền tĩnh (dự phòng khi cần ảnh, không mở được trình duyệt) |
+| `apply_asset(variant, dst, backup_dir, project_root)` | Backup bản gốc **rồi** ghi đè bằng biến thể đã duyệt |
+| `generate_image(prompt, image_paths, out_dir)` | Sinh ảnh thô qua Gemini web (KHÔNG tách nền) — **chính là backend sinh ảnh A**, chạy 2 lượt rồi đưa raw qua `process_raws`. Trả về *chuỗi*, không phải dict |
+
+Trong project chỉ để lại **ảnh input/output** dưới `tools/restyle/`. Không có `.py` nào trong project.
+
+## Sinh ảnh — backend
+
+**Preflight trước mỗi lượt:** `auth_status()` / `remote_nodes()` / `health(deep=true)` → biết
+backend nào sống. Rồi gen bằng **mọi backend còn sống** (1 hoặc 2).
+
+| Backend sống | Hành động | Demo |
+|---|---|---|
+| Cả Gemini + Codex | Tuỳ chọn: mỗi AI `N_AI` ảnh (mặc định 2 → tổng 4) **hoặc** chỉ 1 AI nếu user không cần so sánh chéo | `compare.html` với mọi variant có được |
+| Chỉ Gemini | `restyle_asset(n=4)` hoặc `generate_image` ×4 + `process_raws` (prefix `gem`/`v`) | **Vẫn** `compare.html` |
+| Chỉ Codex | `codex` ×4 → `process_raws` (prefix `gpt`) | **Vẫn** `compare.html` |
+| Không cái nào | Dừng, báo user. Không còn đường sinh ảnh | — |
+
+**Không bắt buộc so sánh chéo Gemini vs GPT.** User nói "không cần so sánh chéo" / chỉ còn
+1 backend → gen đủ biến thể bằng backend đó, **vẫn luôn** giao `compare.html` (gốc ↔ các bản
+mới). Prompt dựng từ `reference/prompt-template.md` — **cùng nguyên văn** cho backend nào
+đang chạy, kể cả `{KEY_HEX}` và `{SHAPE_LOCK}`.
+
+> **Antigravity CLI (`agy`, Nano Banana) ĐÃ TẮT.** Trước đây nó là Backend A; giờ vai trò đó
+> là Gemini web. Đừng gọi `agy`, đừng thêm lại nó vào luồng.
+
+### Backend A — Gemini web qua MCP (`generate_image`)
+
+Chạy **2 lượt**, mỗi lượt 1 ảnh, ghi thẳng vào thư mục raw:
+
+```
+generate_image(prompt="<nguyên văn prompt restyle>",
+               image_paths=["<asset gốc>", "<anchor/ref>"],
+               out_dir="tools/restyle/out/<ten>/_raw")
+```
+
+- **`image_paths` đúng thứ tự** `[asset gốc, anchor/ref…]` — "the FIRST image" trong prompt là
+  phần tử đầu. Tối đa 4 ảnh, mỗi ảnh ≤7MB.
+- **Đây là tool DUY NHẤT trong skill trả về *chuỗi*, không phải dict**: thành công thì
+  `"Saved:\n<đường dẫn>"`, hỏng thì chuỗi bắt đầu bằng `Error:`. Phải tự parse đường dẫn và tự
+  kiểm tiền tố `Error:` — đừng đọc field `error` như các tool khác.
+- Cần **cookie Gemini còn sống**. Hỏng cookie thì MCP tự refresh qua Chrome+CDP; vẫn hỏng thì
+  xem bảng "Khi hỏng" (mục cookie).
+- Lỗi `No image URL in response` thường **không phải cookie** mà là prompt bị từ chối — sửa
+  câu cho rõ ("Generate an image of …") rồi chạy lại 1 lượt.
+- Ảnh lưu tên theo timestamp (`20260730_0.png`), không phải `gem1.png`. Cứ giữ nguyên tên đó và
+  truyền **theo thứ tự** vào `process_raws` — bước đó mới đánh số `gem1/gem2`.
+
+### Backend B — Codex CLI (GPT Image 2)
+
+```
+bash client/codex_gen.sh --prompt "<nguyên văn prompt restyle>" \
+  --ref "<asset gốc>" --ref "<anchor/ref>" \
+  --out "tools/restyle/out/<ten>/_raw/gpt<i>.png"
+```
+
+Chạy 2 lượt (i=1,2). `--ref` lặp được, thứ tự `--ref` = thứ tự "FIRST/SECOND image" trong
+prompt. Script tự lo mọi cơ chế codex (exec, snapshot-diff `generated_images/` cho codex mới
+lẫn session-scan cho codex cũ, chọn python chạy được trên Windows). Exit code xem chú thích
+đầu file script; cách xử lý từng mã nằm trong bảng "Khi hỏng".
+
+### Song song & tuần tự
+
+- 2 lượt `codex` phải **TUẦN TỰ** — snapshot-diff của script không an toàn khi 2 lượt chạy đè nhau.
+- 2 lượt Gemini cũng chạy tuần tự (mỗi lượt mở một chat mới; đừng đua).
+- Gemini và `codex` chạy **SONG SONG với nhau** được (hai hệ độc lập) — nhưng `generate_image` là
+  tool MCP nên nó chặn lượt; muốn song song thì chạy `codex_gen.sh` ở chế độ nền trước, rồi gọi
+  `generate_image` trong lúc script chạy.
+
+### Sau khi có ảnh thô → `process_raws`
+
+Gọi **một lần cho mỗi backend đã sinh** (chỉ gọi backend nào có raw):
+
+```
+# Chỉ Gemini:
+process_raws(raws=[...gem raws...], src=<asset>, key=<key>, out_dir=..., prefix="gem")
+# Chỉ Codex:
+process_raws(raws=[".../gpt1.png", ".../gpt2.png", ...], src=<asset>, key=<key>,
+             out_dir=..., prefix="gpt")
+# Cả hai (tuỳ chọn): gọi cả hai block trên
+```
+
+Nhãn `gem*` / `gpt*` / `v*` trên trang đối chiếu để user biết nguồn. Luật đọc
+`variants[]`/`flags` y hệt `restyle_asset` (xem Bước 2).
+**Khi retry một backend**: sinh thêm ảnh thô mới rồi gọi lại `process_raws` với **TOÀN BỘ raw
+của backend đó** (cũ + mới, cùng `prefix`) — đánh số lại từ đầu, không lo file đè lệch; tách nền
+lại vài ảnh chỉ tốn vài giây, không tốn lượt sinh.
+
+> **Ảnh NỀN tràn viền thì thêm `full_bleed=True`** (nền màn hình, tranh phủ kín khung — chủ thể
+> chạm vành ảnh là đúng thiết kế). Không thêm thì **mọi** bản sinh bị đánh `bad_background` oan dù
+> tách nền hoàn hảo. Sprite/icon/asset rời → **để mặc định**, ở đó lề nền là yêu cầu thật.
+> Xem § Tách nền.
+
+Mỗi variant giờ có thêm `cutout_method` (cách tách nền đã **thắng điểm** cho ảnh đó) và
+`cutout_table` (điểm mọi ứng viên, kể cả bị loại). Không phải chọn gì — tool tự chạy nhiều cách
+rồi lấy bản tốt nhất. Chỉ đọc khi cần biết *vì sao* một bản sạch/bẩn.
+
+### Thiếu backend thì sao (vẫn phải show demo)
+
+- **Thiếu Codex / chỉ Gemini** → báo ngắn ("chỉ Gemini"), sinh **4 ảnh** bằng Gemini
+  (`restyle_asset(n=4)` gọn hơn — tên `v1..v4`). **Bắt buộc** `make_compare_sheet` →
+  `compare.html` như bình thường.
+- **Gemini chết / chỉ Codex** → báo ngắn ("chỉ GPT/Codex"), sinh **4 ảnh** bằng `codex`
+  (`gpt1..gpt4` + `process_raws` prefix `gpt`). **Bắt buộc** `compare.html`. Đồng thời có thể
+  sửa cookie/DNS Gemini theo bảng "Khi hỏng" (không chặn lượt hiện tại).
+- **User không cần so sánh chéo** (kể cả khi cả hai sống) → chọn **1 backend** (ưu tiên cái
+  đang healthy), gen 4 bản, vẫn `compare.html`.
+- **Mất cả hai** → dừng, báo user. Không còn đường sinh ảnh — **không** dựng compare rỗng.
+- Ảnh Gemini/`codex` ra 1024×1024 hoặc lớn hơn — kệ nó, `process_raws` bám size gốc sau.
+
+## Chế độ Screen Sheet — reskin cả màn hình (độc lập với luồng theo-asset)
+
+**Khi nào dùng:** user đưa/nhờ chụp **screenshot một màn hình game** và muốn reskin cả màn
+— thay vì restyle từng asset lẻ. Một lượt sinh cho ra MỘT ảnh gồm: nửa trên là **mockup cả
+màn hình đã đổi style** (giữ nguyên layout — duyệt tổng thể được ngay), nửa dưới là **dải
+chi tiết** (nút, icon, panel…) vẽ rời nhau trên nền key để cắt thành asset. Ưu điểm so với
+per-asset: **cả bộ chi tiết cùng ra trong một ảnh nên tự đồng bộ style với nhau và với
+mockup**. Luồng theo-asset (anchor/batch) không thay đổi gì — hai chế độ dùng chung style
+preset, backend CLI và trang review.
+
+1. **Screenshot**: user đưa ảnh màn hình, hoặc chụp từ game đang chạy. Ảnh này là "asset
+   gốc" của chế độ này.
+2. **Style preset**: y hệt Bước 1 của luồng cũ (dùng chung file `styles/<ten>.md`).
+3. **Chọn key**: `plan_asset(<screenshot>, avoid=[<bảng màu style preset>])` → `key` an
+   toàn cho dải chi tiết (tránh cả màu màn hình lẫn màu style).
+4. **Liệt kê chi tiết** (`{ELEMENT_LIST}`): nhìn screenshot, liệt kê tường minh và ĐẾM các
+   chi tiết muốn cắt ("the play button, the coin icon, ... — exactly 5 elements"). Đừng
+   viết "all UI elements" — model bám danh sách đếm được tốt hơn nhiều.
+5. **Sinh sheet bằng backend đang sống** — prompt theo `reference/prompt-template.md`
+   § *Screen sheet*, ảnh vào = `[<screenshot>]` (+ ≤2 ref style). Mặc định **1 sheet / backend
+   sống** (một sheet đã chứa nguyên bộ). Cả hai sống + muốn so sánh chéo → mỗi AI 1 sheet;
+   chỉ 1 backend → 1–2 sheet từ backend đó. Lưu thô về `out/<man-hinh>/_raw/{gem|gpt}_sheet.png`.
+6. **Mổ sheet**: nhìn sheet thật để ước `mockup_frac` (ranh giới mockup/dải — model hay
+   lệch khỏi 50%), rồi `slice_sheet` **cho mỗi sheet đã sinh** (prefix `gem`/`gpt`):
+   ```
+   slice_sheet(sheet=".../_raw/<prefix>_sheet.png", key=<key bước 3>,
+               out_dir="tools/restyle/out/<man-hinh>", prefix="<prefix>", mockup_frac=0.5)
+   ```
+   → `<prefix>_mockup.png` + `<prefix>1..N.png`. `key_auto` và luật flags như `process_raws`.
+   So `n_cells` với số chi tiết đã liệt kê — **model vẽ thiếu/thừa/dính nhau là chuyện thường**:
+   thiếu thì sinh lại 1 lượt hoặc bù bằng luồng theo-asset; hai chi tiết dính nhau thành 1 cell
+   thì tăng khoảng cách trong prompt ("space them WELL APART") rồi sinh lại.
+7. **Review — BẮT BUỘC một file HTML đối chiếu** (kể cả chỉ 1 backend). `slice_sheet` đã trả
+   sẵn `compare_groups` (mockup + cells) — nối mọi lượt đã chạy, gộp theo `name`, rồi
+   `make_compare_sheet`:
+   ```
+   groups=[{"name":"Màn hình (mockup)","original":"<screenshot gốc>",
+            "variants":[{"label":"<prefix>_mockup","image":"..."}, ...]},
+           {"name":"Cells cắt ra","original":null,
+            "variants":[{"label":"<prefix>1","image":"..."}, ...]}]
+   ```
+   Nhóm mockup lấy **screenshot gốc làm `original`** → nhấn giữ là lật về màn hình cũ, đó là
+   cách duy nhất thấy layout có bị xê dịch không. Nhóm cells để `original: null` vì cell là
+   asset MỚI, không có bản gốc 1-1. Gửi đường dẫn file cho user chọn — **chỉ 1 AI cũng đủ demo**.
+8. **Dùng cells**: cells là asset MỚI, kích thước tự nhiên theo sheet. Muốn thay 1-1 một
+   asset cũ trong project → coi cell như ảnh thô: `process_raws(raws=[<cell>],
+   src=<asset gốc>, key=<key>, ...)` để bám size, rồi `apply_asset` như luồng cũ (mọi rào
+   an toàn backup giữ nguyên).
+
+**Giới hạn phải nói trước với user:** mockup là cả một màn hình — đúng vùng "chủ thể phức
+tạp" của giới hạn *Style transfer yếu dần* ở trên, nên mockup chủ yếu để **duyệt hướng
+style tổng thể**, đừng hứa nó pixel-perfect; thứ dùng thật là các cell. Text trong mockup
+gần như chắc chắn sai font/lỗi chữ — nếu màn có nhiều chữ, nhắc user rằng chữ sẽ làm lại
+bằng font thật trong game, không lấy từ ảnh.
+
+## Chế độ Thumbnail — 3 tỉ lệ cửa hàng (độc lập với luồng theo-asset)
+
+**Khi nào dùng:** user nói "tạo thumb game", "làm thumbnail", "ảnh quảng bá game" và đưa
+**style + screenshot Home + các asset cần thiết**.
+
+**Ra 3 file, đúng số pixel:**
+
+| Tỉ lệ | Yêu cầu cửa hàng | File giao |
+|---|---|---|
+| 1:1 | tối thiểu 512×512 | **1024×1024** (nguồn vốn 1024 — hạ về 512 là bỏ chi tiết không lý do; yêu cầu là SÀN) |
+| 5:7 | đúng 540×756 | **540×756** |
+| 16:9 | tối thiểu 1280×720 | **1280×720** |
+
+**Thumbnail KHÔNG đi qua tách nền.** Nó là tranh full-bleed — đừng gọi `process_raws` /
+`restyle_asset` / `plan_asset` / `slice_sheet`, cũng không cần màu key. Chỉ `generate_image`
+(+ `codex_gen.sh`) rồi `make_thumbs`.
+
+**Model KHÔNG cho chọn kích thước đầu ra** — nó trả size riêng của nó. Đo thật trên Gemini web:
+yêu cầu vuông → 1024×1024, dọc → 864×1216, ngang → 1376×768. Tức nó **tôn trọng hướng** và rơi
+rất sát mục tiêu, nên luồng đúng là sinh ở tỉ lệ gần nhất rồi để `make_thumbs` cắt bù (đo được
+chỉ mất **0–0.8%**) và resize về đúng pixel. Đừng hứa với user rằng model vẽ đúng size.
+
+Các bước:
+
+1. **Chốt style + đọc screenshot Home.** Nhìn screenshot rồi tự liệt kê chủ thể/thế giới của
+   game; hỏi user asset nào là **hero element**.
+2. **Chọn ≤4 ảnh vào** (giới hạn cứng): screenshot Home luôn đứng đầu, rồi tối đa 3 asset/ref.
+   Nhiều hơn → lấy cái nào xuất hiện to nhất trong thumb, **nói rõ cái nào bị bỏ**.
+3. **Sinh 3 lượt RIÊNG, mỗi tỉ lệ một lượt**, prompt ở `reference/prompt-template.md`
+   § Thumbnail — chỉ đổi khối `{ORIENTATION}`. **Đừng cắt 3 size từ một ảnh**: 16:9 → 5:7 mất
+   ~60% khung, chủ thể bị chặt. Dùng backend đang sống (1 hoặc cả hai nếu muốn so sánh);
+   **luôn** giao `compare.html` / sheet duyệt dù chỉ 1 AI.
+4. **Đưa về đúng size:**
+   ```
+   make_thumbs(sources=[
+       {"raw": ".../_raw/<vuông>",  "preset": "1:1"},
+       {"raw": ".../_raw/<dọc>",    "preset": "5:7",  "anchor": "top"},
+       {"raw": ".../_raw/<ngang>",  "preset": "16:9"},
+   ], out_dir="tools/restyle/thumbs/<ten-game>", prefix="gem")
+   ```
+   - `anchor="top"` cho bản dọc: thumb dọc hay dồn chủ thể lên trên, cắt giữa dễ liếm mất đỉnh.
+   - **Đọc `warnings[]`**: `upscaled` nghĩa là nguồn NHỎ hơn đích → đã phóng to (xem
+     `upscale_method`; `lanczos` = sẽ mềm, `esrgan` = đã dựng nét nhưng chi tiết là model ĐOÁN).
+     Sinh lại nguồn, đừng giao bản mềm.
+   - `prefix` mang nhãn backend (`gem`/`gpt`) — hai lần gọi cùng prefix sẽ **ghi đè nhau**.
+     Trong CÙNG một lời gọi, hai nguồn cùng preset tự được đánh số `_2`.
+5. **Giao trang đối chiếu** (bắt buộc như mọi lượt thiết kế). Mỗi tỉ lệ một group, `original` =
+   screenshot Home để lật xem thumb có đúng game hay không:
+   ```
+   groups=[{"name":"1:1 (1024×1024)","original":"<screenshot Home>",
+            "variants":[{"label":"gem","image":".../gem_1x1.png"},
+                        {"label":"gpt","image":".../gpt_1x1.png"}]},
+           {"name":"5:7 (540×756)", "original":"<screenshot Home>","variants":[...]},
+           {"name":"16:9 (1280×720)","original":"<screenshot Home>","variants":[...]}]
+   ```
+
+**Nói trước với user:** prompt **cấm hẳn chữ/logo** vì model sinh ảnh viết chữ méo và sai chính
+tả gần như luôn luôn — thumb có chữ rác thì phải sinh lại cả ảnh. Logo/tiêu đề chèn sau bằng
+công cụ khác. Đây là hạn chế của model, không phải thiếu sót của prompt.
+
+## Tách nền: CHẠY NHIỀU CÁCH RỒI CHẤM ĐIỂM CHỌN BẢN TỐT NHẤT
+
+**Không tin sẵn cách nào.** `process_raws` / `restyle_asset` / `slice_sheet` chạy **mọi cách khả
+dụng** trên từng ảnh, chấm điểm bằng chỉ số đo được, rồi giao ra bản thắng. Đây là mặc định, không
+phải tuỳ chọn.
+
+**Vì sao**: đo thật 10 cách trên 4 bản sinh — *không cách nào thắng mọi ảnh*.
+
+| Cách | Điểm mạnh | Thất bại ở đâu (đo thật) |
+|---|---|---|
+| `unmix` | nghịch đảo đại số phương trình ghép ảnh | cần có phông key để dò màu nền |
+| `chroma-bg` | chroma-key theo màu nền **đo được** | viền còn ám màu nền (cast 382) |
+| `chroma-key` | chroma-key theo màu **yêu cầu** — lưới an toàn | model vẽ lệch màu → sót nguyên nền |
+| `ben2` | mép lông/tơ, ảnh **không có** phông key | ảnh nền full-bleed: **ăn mất 8.99% chủ thể**, mép nhoè thành dải 77.425 px |
+
+**4 tiêu chí chấm** (điểm thấp = tốt), mỗi cái bắt một kiểu hỏng riêng — thiếu cái nào là mở đường
+cho một cách dở thắng điểm:
+
+| Tiêu chí | Bắt lỗi gì |
+|---|---|
+| `cast` | viền còn ám màu nền, đo khi ghép lên **trắng và đen** |
+| `f_err` | giữ nguyên màu đã bị nền trộn vào (so với nghịch đảo đại số) |
+| `fg_loss` | ăn vào **lòng** chủ thể → **loại thẳng** nếu > 2% |
+| `bg_residue` | để nguyên nền → **loại thẳng** nếu > 2% |
+
+`cast` và `f_err` phải đi **cùng nhau**: cách nào để `alpha=255` khắp dải AA sẽ có `f_err≈0` *hiển
+nhiên* (khi α=1 thì "màu đúng" chính là màu đã bị trộn) — chỉ `cast` bắt được ca đó.
+
+**Đọc kết quả**: `cutout_method` = cách đã thắng cho ảnh đó · `cutout_table` = điểm của **mọi** ứng
+viên kể cả bị loại (biết *vì sao* nó thắng) · `remover` ở cấp ngoài = danh sách ứng viên khả dụng
+(`multi` / `multi+ben2`), **không** phải cách đã dùng.
+
+Đo thật trên `home_grass` (4 ảnh nền): `unmix` thắng cả 4, điểm **0.0018–0.0025** so với
+**1.25–2.06** của chroma — cách nhau ~500×. cast **0**, `bg_residue` **0.0000**.
+
+### `full_bleed=True` — BẮT BUỘC cho ảnh nền tràn viền
+
+Ảnh nền (background plate) có tranh phủ kín khung nên chủ thể **chạm vành ảnh là đúng thiết kế**.
+Cửa gác `border_impurity` lại giả định vành ảnh toàn là nền → **mọi ảnh nền đều bị đánh
+`bad_background` dù tách nền hoàn hảo** (đo thật: cast 0, `bg_residue` 0.0000, vẫn báo hỏng cả 4).
+
+Không suy ra được từ pixel — "thảm cỏ chạm vành dưới" và "mảng panel chưa key chạm vành trên" đều là
+nội dung đục chạm vành, chỉ khác **ý định**. Tỉ lệ vành mang màu key cũng không tách được: 0.552 ở ca
+*cần* gác so với 0.225–0.390 ở ảnh nền *cần tắt* gác — quá gần để đặt ngưỡng. **Nên phải nói ra.**
+
+- Ảnh nền / thumbnail → `full_bleed=True`
+- Sprite / icon / asset rời → **để mặc định `False`** (ở đó lề nền là yêu cầu thật)
+- Nó chỉ tắt riêng `border_impurity`; `bg_residue` / `coverage` / bộ chấm điểm vẫn gác như thường
+
+### BEN2 (một ứng viên, không còn độc quyền)
+
+`PramaLLC/BEN2` — matting ngữ nghĩa qua PyTorch (https://huggingface.co/PramaLLC/BEN2), xem
+`client/bgremove.py`. Nó **thắng ở ca không có phông key** (ảnh chụp/tranh nền thật) — ở đó
+`unmix`/`chroma` đều bị loại vì phủ kín khung.
+
+- **Model tự chứa**: trọng số (~1GB) tải từ HuggingFace về `models/` ở lần chạy đầu; các
+  lần sau nạp lại từ đó (đặt qua `HF_HOME`). Đổi repo model bằng env `BEN2_MODEL`.
+- **Thiết bị**: mặc định `BEN2_DEVICE=auto` — CUDA nếu máy có GPU, không thì CPU. Ép bằng
+  `BEN2_DEVICE=cpu`/`cuda`. `refine_foreground` **bật mặc định** (đo thật: pixel mép mềm bị
+  xanh trội tụt 58% → 25%, tốn thêm ~0.4s/ảnh) — tắt bằng `BEN2_REFINE=0` nếu máy yếu.
+- **Cài đặt**: `pip install torch "ben2 @ git+https://github.com/PramaLLC/BEN2.git"` (đã có trong
+  `server/requirements.txt`). Thiếu `torch`/`ben2` thì nó chỉ **vắng khỏi danh sách ứng viên**,
+  không lỗi — các cách theo màu vẫn chạy đủ.
+- **Giá**: BEN2 là ứng viên đắt nhất. Đo thật trên 4 ảnh ~852×1846: **~5.0s/ảnh** khi có BEN2 so với
+  **~2.5s/ảnh** khi không. Vẫn nên bật — nó là cách duy nhất cứu được ca không có phông key.
+- **Màu key giờ chỉ để TĂNG TƯƠNG PHẢN** cho model vẽ nền phẳng, KHÔNG còn là cơ chế xóa duy nhất.
+  `key_safe`/`key_margin` của `plan_asset` không còn là rào cản chất lượng — chủ thể trùng màu key
+  vẫn tách tốt (ràng buộc **liên thông**: vùng trùng màu nền nằm trong lòng chủ thể không bị xoá,
+  muốn bị xoá thì phải nối được ra tới vành ảnh).
+
+## Phóng to: khi bản sinh NHỎ HƠN size cần
+
+Model sinh ảnh không cho chọn kích thước đầu ra. Khi khung đích **lớn hơn** ảnh sinh, LANCZOS chỉ
+trải mép ra cho mềm đi — nó không có thông tin nào để thêm. `hlky/RealESRGAN_x4plus_anime_6B` thì
+dựng lại nét, và bản `anime_6B` được huấn luyện riêng cho tranh vẽ — đúng loại ảnh của skill này.
+
+**Cũng chạy nhiều cách rồi chấm điểm chọn**, giống đường tách nền. Tự động trong
+`process_raws` / `restyle_asset` / `make_thumbs`; gọi tay bằng `upscale_image`.
+Ảnh sinh thường TO hơn asset game nên phần lớn lượt chạy sẽ **không đụng tới** bước này.
+
+| Cách | Khi nào thắng |
+|---|---|
+| `lanczos` | hoạ tiết dày, nét mảnh san sát — chỗ model bịa nhiều nhất. Luôn có mặt, là lưới an toàn |
+| `esrgan` | mặc định thắng: model 4x rồi LANCZOS thu về đúng đích |
+| `esrgan-pre` | chỉ dựng khi đích > 4x — LANCZOS lên đích/4 TRƯỚC rồi mới cho model chạy sau cùng |
+
+| Tiêu chí | Vai trò | Bắt lỗi gì |
+|---|---|---|
+| `blur` | **xếp hạng** (trọng số 3.0) | ảnh mềm nhũn — năng lượng gradient so với mốc NEAREST |
+| `ring` | **xếp hạng** (0.40) | quầng sáng & chi tiết bịa ra — thứ `blur` chấm NGƯỢC |
+| `lr_err` | phá thế hoà (0.05) + **loại thẳng** > 30 | bịa nội dung mâu thuẫn ảnh nguồn |
+| `cov_err` | **loại thẳng** > 0.08 | matte bị ăn mòn hoặc phình ra |
+
+Đọc `upscale_method` (cách thắng) và `upscale_table` (điểm mọi ứng viên).
+
+### Phép thử hiển nhiên cho kết luận SAI — đừng lặp lại
+
+Cách kiểm tra tự nhiên nhất là **thu nhỏ ảnh sắc nét rồi phóng lại và so với bản gốc**. Làm thế thì
+LANCZOS thắng **20/20** ca. Kết luận đó **sai**, vì phép thử thiên vị từ trong thiết kế: ảnh nhỏ được
+tạo bằng LANCZOS-thu-nhỏ nên LANCZOS-phóng-to gần đúng là phép **nghịch đảo của chính nó**. Ảnh AI
+sinh ra chưa từng đi qua bộ lọc nào.
+
+Phép thử không thiên vị: **vẽ cùng một cảnh ở cả hai độ phân giải** (4 cảnh × 5 độ phân giải nguồn ×
+4 hệ số × có/không alpha = 160 ca, không ảnh nào suy ra từ ảnh kia). Kết quả:
+
+| Thước đo | lanczos | esrgan | esrgan-pre |
+|---|---|---|---|
+| RMSE (sai số pixel) | 113 | 33 | 14 |
+| **LPIPS (cảm nhận)** | 17 | **107** | 36 |
+
+Hai thước đo **không đồng ý ở 61% số ca** và ngược hướng nhau. Đây là đánh đổi
+*distortion–perception*: khi ảnh nhỏ không đủ thông tin để biết cạnh nằm chính xác ở đâu, ước lượng
+tối ưu theo bình phương sai số là một cạnh **mờ** — trung bình của mọi khả năng. LPIPS trung bình:
+lanczos 0.104–0.189 so với esrgan 0.036–0.079, tức **tốt hơn 2–4 lần ở mọi độ phân giải nguồn**.
+
+Trọng số được dò theo LPIPS: **đúng 87.5% trên phần huấn luyện VÀ 87.5% trên nửa giữ lại**.
+Hai điều đi ngược trực giác, ghi lại để khỏi "dọn dẹp" nhầm:
+
+- **Bỏ `ring` đi thì độ đúng tụt xuống 66.9%** — đúng bằng mức của "cứ luôn chọn esrgan", tức bộ
+  điểm không còn đóng góp gì. Chính `ring` bắt được nhóm ca mà LANCZOS thật sự thắng.
+- **`lr_err` và `cov_err` dò ra trọng số tối ưu bằng 0.** Đẩy `lr_err` lên 0.2 làm độ đúng tụt còn
+  80.6% — vì nó chính là RMSE thu nhỏ lại, mang nguyên thiên vị thưởng ảnh mờ. Chúng sống bằng vai
+  trò **loại thẳng**, không phải xếp hạng.
+
+### Alpha và viền
+
+- **Alpha đi qua chính model** (dưới dạng ảnh xám), không phải LANCZOS: thắng **9/9** ca, sai số
+  matte giảm hơn nửa (3.87 so với 8.98). Đổi bằng `imglib.upscale_rgba(..., alpha_esrgan=False)`.
+- **Màu tiền cảnh được loang ra vùng trong suốt TRƯỚC khi phóng** — bắt buộc, không phải tinh chỉnh.
+  Sau tách nền, pixel nền vẫn mang màu key trong kênh RGB (vô hình vì alpha 0), mà model chỉ nhìn
+  RGB nên nó thấy magenta thật và kéo vào mép, phá đúng cái viền vừa làm sạch tới mức cast = 0.
+
+### Vận hành
+
+- **Model tự chứa**: trọng số (~18MB) tải từ HuggingFace về `models/` ở lần chạy đầu. Đổi repo
+  bằng env `ESRGAN_MODEL`. **Không cần `basicsr`/`realesrgan`** — `client/upscale.py` tự dựng RRDBNet
+  bằng torch thuần, vì `basicsr` import `torchvision.transforms.functional_tensor` đã bị gỡ khỏi
+  torchvision >= 0.17 (máy này 0.19) nên cài vào sẽ gãy.
+- **Thiết bị**: `ESRGAN_DEVICE=auto` (mặc định) / `cpu` / `cuda`. `ESRGAN_FP16=0` để tắt nửa độ chính
+  xác. Ảnh lớn được **chia ô** (`ESRGAN_TILE`, mặc định 512) với lề chồng lấn `ESRGAN_TILE_PAD`=32 —
+  đo thật: có lề thì kết quả trùng bản không chia ô (lệch tối đa 1 mức), bỏ lề thì lệch tới 180.
+- **Giá**: ~4s/ảnh khi phóng 3× ảnh ~900×900 trên RTX 3060. Hết VRAM thì tự hạ cạnh ô rồi rớt về CPU.
+- **Thiếu `torch`** → chỉ còn `lanczos`, **không lỗi**.
+
+> **Đây KHÔNG thay được việc sinh lại ở đúng độ phân giải.** Chi tiết thêm vào là model **đoán**.
+> Ưu tiên vẫn là sinh nguồn to hơn; phóng to là cách chữa cháy.
+
+## Dùng chung một máy trong LAN (tuỳ chọn)
+
+Một máy có cookie Gemini + `codex login` + GPU; các máy khác **mượn** qua mạng. Kiến trúc &
+lý do: `reference/remote-lan.md`. Hướng dẫn thực hành cho **máy khách** (cài, cấu hình `.env`,
+kiểm tra, khắc phục): `reference/client-guide.md`.
+
+**MỖI NODE**: đặt token trong `server/.env` (`GAMEART_REMOTE_TOKEN` >= 16 ký tự, không có thì
+node từ chối chạy) rồi **`server\start-node.cmd`** (chạy ngầm, `stop-node.cmd` để dừng; hoặc
+`python server/remote_host.py --host <IP LAN> --port 8765` để foreground).
+**MÁY KHÁCH**: đặt `GAMEART_REMOTE_NODES` (danh sách URL) + `GAMEART_REMOTE_TOKEN` trong `client/.env`.
+**Không đổi gì khác** — tên tool và dòng lệnh `codex_gen.sh` giữ nguyên từng chữ. Để giao cho máy
+khách một **bản gọn không chứa file node** (không `remote_host.py`, không models, không cookie):
+`python server/pack.py` → **`game-art-client.zip`** (máy khách) + **`game-art-node.zip`** (node), đều không kèm token/model. Node tự tải model lúc khởi động. Xem `reference/client-guide.md` + § LAN trong `reference/remote-lan.md`.
+
+**Nhiều node thì tự chọn**: xếp hạng theo node rảnh nhất + còn nhiều quota → node báo bận/hết quota
+thì **đổi ngay** sang node kế → hết node dùng được thì **chờ tối đa 15 phút** rồi báo lại kèm lý do
+từng node. Xem cả cụm bằng `remote_nodes()` (tải, quota, vì sao node nào bị bỏ qua).
+
+> **ĐỪNG mở `gemini_image_mcp.py` ra mạng.** 11/12 tool của nó nhận đường dẫn đọc/**ghi** tuỳ ý
+> (`out_dir`, `dst`, `image_paths`…) nên expose nó = cấp quyền đọc/ghi ổ đĩa cho mọi máy trong
+> tầm. `remote_host.py` mới là bản đúng: **không tham số đường dẫn nào**, ảnh đi bằng base64.
+
+Chỉ ba thứ đi qua mạng — sinh ảnh, BEN2, ESRGAN. **Chấm điểm và chọn bản tốt nhất vẫn chạy ở máy
+khách**, nên nó giữ nguyên quyền quyết định; máy chủ tắt thì chỉ mất ứng viên BEN2/ESRGAN, các
+cách theo màu và LANCZOS vẫn đủ để pipeline chạy tiếp. Có GPU tại chỗ thì **luôn ưu tiên local**.
+
+Ba rủi ro phải nói trước: dùng chung = **chung tài khoản** (dùng tài khoản phụ); **codex chạy
+tuần tự** nên nhiều máy sẽ chờ nhau; token là **mật khẩu chung**, chỉ hợp cho LAN tin cậy.
+
+## Hai giới hạn THẬT của công cụ này — đọc trước khi hứa với user
+
+Cả hai đều đo được trên asset thật, không phải lo xa.
+
+### 1. Asset bị `setTint` lúc chạy thì KHÔNG ĐƯỢC restyle
+
+Rất nhiều game Phaser dùng kiến trúc **mặt nạ trắng + tint lúc chạy**: asset cố tình là hình
+trắng trơn, code bơm màu vào bằng `setTint`. `setTint` là phép **NHÂN**:
+`màu hiện ra = màu texture × màu tint`.
+
+Restyle một asset như thế thành "teal viền vàng" rồi để game nhân nó với tint → **ra màu bùn,
+toàn bộ hệ màu của game vỡ**. Ca thật (MeoBlock): `cell_base`, `cell_completed_ear`,
+`ic_hard_base`, `rule_unknown` và toàn bộ icon top-bar đều bị tint — chiếm phần lớn asset.
+
+**BẮT BUỘC kiểm trước khi restyle bất cứ asset nào:**
+```bash
+grep -rn "setTint" src/ --include=*.js | grep "<tên asset>"
+```
+Có tint → **loại khỏi danh sách**, nói rõ với user vì sao. Muốn đổi tông cho nhóm này thì sửa
+**hằng số màu trong code** (vd `src/core/config.js`), không phải sửa asset — vừa tức thì, vừa
+không tốn lượt sinh, vừa không có rủi ro AI vẽ sai.
+
+Đừng phân loại asset bằng cách nhìn tên file. Phải đọc code.
+
+### 2. Style transfer YẾU DẦN khi chủ thể phức tạp
+
+Đo được trên cùng một style, cùng một anchor:
+
+| Asset | Độ phức tạp | Kết quả |
+|---|---|---|
+| `btn_hard` (một thanh trơn) | thấp | Style bám **đầy đủ**: bevel vàng dày, gradient dọc, specular |
+| `home_cats` (10 khối + mặt + bố cục) | cao | Style bám **yếu**: chỉ thêm viền vàng mảnh, render vẫn phẳng như asset gốc |
+
+Model có ngân sách chú ý hữu hạn. Chủ thể phức tạp → nó dồn hết vào giữ hình dạng và **rơi về
+phong cách render của ảnh gốc**. Không phải lỗi prompt, không phải lỗi ảnh mẫu — thêm ref hay tả
+kỹ hơn đều không cứu được (đã thử cả hai).
+
+**Hệ quả thực hành:** chọn anchor là asset **đơn giản** — style sẽ ra rõ nhất và user duyệt được
+đúng cái họ sẽ nhận. Với asset phức tạp, hạ kỳ vọng và nói trước với user, đừng để họ tưởng cả bộ
+sẽ bóng như cái anchor.
+
+## Bất biến
+
+- **Không bao giờ ghi đè asset gốc khi user chưa duyệt bằng mắt.** Sinh → staging → contact
+  sheet → user chọn → mới `apply_asset` (có backup, và backup không bao giờ bị ghi đè bởi lần
+  `apply` sau — nó luôn giữ bản gốc THẬT SỰ đầu tiên).
+- **Cả bộ phải đồng nhất.** Một asset đã duyệt trở thành *golden anchor*, mọi asset sau bám theo nó.
+- **Các tool trả về `dict` (JSON có cấu trúc), KHÔNG raise, KHÔNG dùng exit code.** Hỏng thì trả
+  `{"error": "..."}`. Luôn kiểm field `error` trước khi coi kết quả là thành công. (`generate_image`
+  là ngoại lệ lịch sử: nó trả *chuỗi* bắt đầu bằng `Error:` khi hỏng — nhưng restyle thì dùng
+  `restyle_asset`, không dùng `generate_image` trực tiếp.)
+- **`restyle_asset` VÀ `process_raws` trả `variants[]` cùng cấu trúc; mỗi phần tử báo qua field `flags` (một list)**, không chỉ
+  `status`. Một bản sinh có thể hỏng NHIỀU kiểu cùng lúc (vd chủ thể vừa bị ăn thủng vừa bị mờ).
+  `status` chỉ là flag nặng nhất — giữ để tương thích — nhưng luôn đọc `flags` đầy đủ. Có 5 flag:
+  `bad_background`, `bad_subject`, `bad_translucent` (cả ba là LỖI, cần retry — xem bảng "Khi hỏng"),
+  và **`sparse`**, **`bad_holes`** (cả hai chỉ **THAM KHẢO** — KHÔNG phải lỗi, KHÔNG chặn ghi file;
+  contact sheet là cửa gác thật sự, không phải hai flag này):
+  - `sparse` → chủ thể nhỏ (coverage thấp) nhưng ĐẶC (solid_ratio cao) — vd icon/line-art
+    mảnh. Không phải hỏng, chỉ đáng chú ý khi soi sheet.
+  - `bad_holes` → có vùng trong suốt đáng ngờ NẰM GIỮA chủ thể (`hole_ratio` cao) — có thể là
+    màu key ăn thủng một chi tiết bên trong, hoặc có thể là art hollow hợp lệ (nhẫn, chữ "O",
+    khung ảnh). Ngưỡng KHÔNG hoàn hảo — luôn nhìn sheet để phân biệt, đừng tự động loại bỏ.
+- **Tách nền CHẠY NHIỀU CÁCH rồi chấm điểm chọn bản tốt nhất** — xem § Tách nền ở trên. Đọc
+  `cutout_method` (cách đã thắng) và `cutout_table` (điểm mọi ứng viên) trong mỗi variant.
+  Với ảnh NỀN tràn viền phải truyền `full_bleed=True`, không thì mọi ảnh nền đều bị đánh
+  `bad_background` oan.
+- **PHÓNG TO cũng chạy nhiều cách rồi chấm điểm chọn** — xem § Phóng to. Chỉ kích hoạt khi bản
+  sinh NHỎ HƠN khung đích (ảnh sinh thường to hơn asset game nên thường không đụng tới). Đọc
+  `upscale_method` / `upscale_table`. Chi tiết model thêm vào là ĐOÁN — sinh lại nguồn to hơn
+  vẫn tốt hơn phóng to.
+- **Tách nền dùng MÀU NỀN ĐO ĐƯỢC, không dùng màu key đã yêu cầu.** Model gần như không bao giờ
+  vẽ đúng `{KEY_HEX}` — đo thật: yêu cầu `#00FF00`, model vẽ `#0CF508` và `#0BD009` (G=209).
+  Key theo màu YÊU CẦU trên ca thứ hai để lại **100% nền** dưới dạng màng bán trong suốt; key
+  theo màu ĐO ĐƯỢC thì sạch 0 px. Các field trong mỗi variant:
+  - `bg_color_used` — màu THỰC SỰ đã dùng. `bg_sampled_mode` + `bg_mode_share` — màu **mode**
+    trên vành đã lọc theo màu key, và tỉ lệ vành nó chiếm. `bg_source` cho biết màu đó từ đâu:
+    `mode_vien` (dò được) / `duoc_truyen_vao` / `khong_thay_mau_key_o_vien` (vành không có mảng
+    màu-key nào đáng kể → quay về màu yêu cầu).
+  - **Dò bằng MODE, không phải MEAN, và mode phải LỌC theo màu key yêu cầu.** Hai bẫy đo được:
+    (a) `sample_border_color` dùng mean nên với ảnh nền full-bleed (nửa trên trời màu key, nửa
+    dưới thảm cỏ tràn ra tận vành) nó trả `#AC4978` — **bùn tím, màu không có thật trong ảnh** —
+    với `purity 0.0002`, tức cửa auto-key không bao giờ mở; (b) mode **toàn cục** thì chỉ đúng
+    NHỜ MAY: nó thắng trên ảnh thật vì nền key phẳng còn thảm cỏ có vân, nhưng nếu chủ thể phẳng
+    và chiếm nhiều vành hơn nền thì mode trả về **màu chủ thể** và key theo nó sẽ xoá mất chính
+    chủ thể. Lọc theo màu key yêu cầu thì hết phụ thuộc vân bề mặt.
+  - `key_auto: true` + `key_requested` — màu đã dùng lệch hẳn màu yêu cầu. **Bình thường, không
+    phải lỗi**, gặp rất thường xuyên.
+  - `band_w` — bề rộng dải anti-alias **đo từ ảnh**, không phải hằng số. Đo thật: **2px** ở bản
+    GPT nhưng **7–8px** ở bản Gemini (chân trời vẽ nhoè). Hằng số cố định thì hoặc sót viền hoặc
+    gặm chủ thể — bản đầu cố định 2px để lại **433 px viền hồng đục** trên ảnh Gemini.
+  - `bg_px_removed` — số pixel nền sót mà `strip_bg_residue` đã xoá. Lớp này chỉ xoá vùng
+    màu-nền **liền mạch với nền đã trong suốt** (hoặc chạm vành ảnh), nên art nằm kín trong
+    lòng chủ thể không bao giờ bị chạm.
+  - `bg_residue` — tỉ lệ pixel còn đục mà VẪN mang màu nền, đo trên ảnh ĐÃ tách. `> 0.02` →
+    cờ `bad_background`. Trước đây đường BEN2 ép `border_impurity = 0` nên **không cờ nào báo
+    được nền sót** và lỗi đi thẳng vào asset; `bg_residue` là cửa gác thật cho đường đó.
+  - `coverage`/`solid_ratio`/`hole_ratio`/`border_impurity` đo trên **bản chẩn đoán**
+    (chroma_key), không phải bản giao ra — vì lớp cờ đọc alpha theo *ngữ nghĩa ramp mềm* của
+    chroma_key ("có nội dung nhưng không đục" = bóng ma / lỗ khoét / nền chưa key), còn `unmix`
+    cố ý cho alpha **gần như nhị phân** nên đo trên nó thì 4 kiểu defect đều tụt xuống `ok`.
+    Các chỉ số đó trả lời "BẢN SINH có dùng được không", độc lập với việc sau đó cắt bằng gì.
+    `out_coverage`/`out_solid_ratio` là số của bản **thực sự giao ra**.
+- **Có một loại "dính nền" mà tách nền KHÔNG cứu được**: model dùng chính hue của key làm **màu
+  nét** trong tranh (ca đã gặp: bánh răng bạc viền xanh lá đậm `(19,78,27)` — cùng hue với key
+  nhưng tối hơn nên cách `#00FF00` tới 362 đơn vị). Đó là art thật, không phân biệt được bằng
+  màu; thử xoá theo hue thì gặm mép thành rỗ. Chặn từ prompt — dòng `Do NOT use {KEY_HEX} or ANY
+  shade of that hue` đã có trong `reference/prompt-template.md`. Thấy asset ra kiểu này thì sinh
+  lại, hoặc đổi `key` sang màu xa bảng màu style hơn.
+- **Watermark ✦ của Gemini: đã xoá TỰ ĐỘNG ngay lúc tải ảnh về, không cần làm gì.** Nó là ngôi sao
+  4 cánh TRẮNG THUẦN alpha CỐ ĐỊNH, phủ ô **48x48 px cách cạnh phải/dưới đúng 96 px** (hiệu chuẩn
+  trên 3 ảnh nền-đen: trùng khít từng pixel, α ≈ 0.305, 3 kênh RGB lệch `0.0`). Vì alpha cố định
+  nên phép trộn ĐẢO ĐƯỢC — `imglib.unwatermark_gemini` lấy lại đúng pixel gốc, sai số ~1 mức, không
+  inpaint đoán. Chạy TRƯỚC mọi thao tác khác (`_strip_wm` lúc tải về; `verify=True` ở đầu
+  `process_raws`/`slice_sheet` cho ảnh Gemini/`codex` vì nguồn lẫn), báo qua `watermark_removed`.
+  Tắt bằng `GEMINI_KEEP_WATERMARK=1`. Chi tiết + vì sao phải xoá sớm: `reference/prompt-template.md`
+  § Watermark ✦.
+- **`speckles_removed` trong mỗi variant: giá trị `0` là BÌNH THƯỜNG** (watermark đã xoá từ trước,
+  nên 2 lớp `despeckle` → `strip_gemini_watermark` sau tách nền giờ chỉ là lưới an toàn cho trường
+  hợp Google đổi hình học). Đừng retry vì con số này. Chỉ để ý khi nó **lớn bất thường** (>3): khi
+  đó có thể chroma key đang vụn asset ra, hãy soi sheet.
+  Vẫn giữ prompt LỀ RỘNG (chủ thể ~60% giữa khung, góc trống rộng) trong
+  `reference/prompt-template.md` — giờ để phục vụ `border_impurity` và tránh chủ thể chạm mép,
+  không còn vì watermark.
+- **Field `out` của mỗi variant nói "có ghi file ra hay không", KHÔNG nói "ảnh có ổn không".**
+  `out: null` nghĩa là không ảnh nào được ghi — `bad_subject`: chủ thể biến mất hoàn toàn, HOẶC vừa
+  nhỏ vừa bị bào mờ thành bóng ma (nhỏ mà vẫn ĐẶC thì không tính — xem `sparse`). `out` có đường dẫn
+  nghĩa là CÓ file — kể cả khi vẫn có `flags` lỗi (`bad_background`, `bad_translucent`) hoặc flag
+  tham khảo (`sparse`, `bad_holes`); file đó vẫn nằm chờ soi trong sheet, không phải asset sạch.
+  **Luôn đọc `status`/`flags`, đừng chỉ nhìn `out`.**
+- **`plan_asset` báo `key_safe` (bool) cùng `key_margin`.** `key_safe=false` nghĩa là margin của
+  asset tới màu key đã chọn KHÔNG đủ xa ngưỡng `chroma_key` dùng để đảm bảo alpha đục hoàn toàn —
+  asset có nguy cơ ra mờ như bóng ma. Kiểm field này ở **CẢ anchor pass lẫn batch pass**, không chỉ
+  anchor — một asset xui trong lô 52 cái vẫn có thể trúng màu key không an toàn.
+- **`plan_asset(src, avoid=[...])`** gộp bảng màu của STYLE PRESET (không phải chỉ palette asset
+  gốc) vào việc chọn key — vì `chroma_key` chạy trên ẢNH ĐÃ RESTYLE, có palette MỚI khác hẳn
+  asset gốc. Luôn truyền bảng màu style preset vào `avoid` khi đã có style (bước 1 xong).
+- **`process_raws`/`restyle_asset` cần `key` KHỚP màu nền mà prompt yêu cầu model vẽ.** Prompt bảo
+  model vẽ nền màu `{KEY_HEX}`; `key` truyền vào tool phải đúng màu đó thì chroma key mới tách trúng.
+  Lấy `key` từ `plan_asset`, nhét vào cả prompt lẫn tham số `key`.
+- **`apply_asset` cần `project_root` cố định.** Không truyền, mirror path của backup phụ thuộc cwd
+  lúc gọi — hai lần `apply` từ hai thư mục khác nhau ra hai backup khác nhau và backup không
+  còn chắc chắn giữ bản gốc thật. Luôn truyền `project_root=<gốc project tuyệt đối>` tường minh.
+
+## Đường dẫn
+
+- Tool: MCP server `gemini-image` (self-contained — chứa cả logic tách nền `imglib`, và là
+  luôn backend sinh ảnh A) + 1 CLI sinh ảnh (`codex` qua `client/codex_gen.sh`).
+- Artifact (trong project đang mở): `tools/restyle/{styles,out,backup}/`.
+  - `out/<ten>/_raw/` = ảnh thô chưa tách nền: ảnh Gemini tên theo timestamp (do
+    `generate_image` ghi thẳng) + `gpt<i>.png` (do `codex_gen.sh` ghi thẳng).
+  - `out/<ten>/gem<i>.png`, `gpt<i>.png` = biến thể đã tách nền, bám size gốc (đường mặc định);
+    `v<i>.png` khi dùng `restyle_asset` (chỉ-Gemini).
+
+## Tham số
+
+- **Số ảnh mỗi lần sinh** = mặc định **4 biến thể/asset** từ backend đang dùng.
+  - Cả hai sống + user muốn so sánh chéo: `N_AI = 2` mỗi AI → tổng 4 (tuỳ chọn, không mặc định bắt buộc).
+  - Chỉ 1 backend (hoặc user bỏ so sánh chéo): **4 ảnh từ backend đó**.
+  User có thể đổi ("mỗi AI 3 bản", "chỉ GPT 4 bản"…). Batch 50+ asset → giữ số thấp, đừng đốt quota.
+- `restyle_asset` (đường chỉ-Gemini) nhận `n`, dùng `n = 4` khi chỉ còn Gemini.
+
+## Bỏ qua asset suy biến
+
+Trước khi chọn asset để restyle (anchor lẫn batch), bỏ qua bất kỳ file nào có width HOẶC
+height dưới **~16px**. Đó không phải art — là một dải màu 1-2px được engine/CSS kéo giãn ra
+làm nền/gradient (từng gặp trong một project thật: `home_bg_fill.png` kích thước 2×2048,
+`finished_bg_gradient.png` kích thước 2×1780). Đưa loại file này vào model sinh ảnh để "redraw the
+subject" là vô nghĩa — không có chủ thể nào để vẽ lại. Dùng `plan_asset(<asset>)` để đọc
+`width`/`height` rồi lọc trước khi đưa vào danh sách xử lý.
+
+## Bước 0 — Preflight
+
+**Kiểm backend trước (đường mặc định):**
+- `auth_status()` / remote `health(deep=true)` → Gemini sống? (`logged_in` + deep OK). Tool
+  **không tốn** lượt sinh ảnh. Cookie chết / DNS fail → xem "Khi hỏng"; **không dừng** nếu Codex còn.
+- Codex sẵn sàng? (`codex` trong remote `available` / `codex --version`). Login fail = exit 5
+  của `client/codex_gen.sh`, xem "Khi hỏng".
+- **≥1 backend sống → tiếp tục** theo mục "Thiếu backend thì sao" (vẫn show `compare.html`).
+  Mất cả hai → dừng.
+
+**MCP `gemini-image` vẫn BẮT BUỘC** (plan/process/sheet/apply chạy trên nó). Nếu máy này
+KHÔNG có cookie Gemini/`codex login`/GPU mà mượn máy khác trong LAN thì `auth_status()` trả
+`mode: "remote"` — xem § Dùng chung một máy trong LAN.
+**Đừng hardcode đường dẫn `gemini_image_mcp.py` của một máy cụ thể** — skill này dùng trên
+nhiều máy/project khác nhau, mỗi máy đăng ký MCP server ở một đường dẫn khác nhau. Tự tìm
+đường dẫn thật đã đăng ký:
+
+```bash
+claude mcp get gemini-image
+```
+
+Code **nằm ngay trong skill này**, đã TÁCH LÀM HAI thư mục cạnh `SKILL.md`:
+- **`client/`** — MCP entry `gemini_image_mcp.py` + `imglib.py` + lớp mượn-node + test. Đây là
+  thứ máy khách chạy; MCP đăng ký trỏ vào `client/gemini_image_mcp.py`.
+- **`server/`** — CHỈ code node (`remote_host.py`, launcher, công cụ cookie). Máy khách không cần.
+- **`models/`** (root) — trọng số model, chỉ node dùng, gitignored.
+
+Để ship: `python server/pack.py` → 2 bản nén `game-art-client.zip` (máy khách) + `game-art-node.zip` (node), không kèm token/model. (`make_client_bundle.py` tạo THƯ MỤC client thay vì zip nếu cần.)
+Chi tiết máy khách: `reference/client-guide.md`.
+
+Đọc output để lấy đường dẫn `.py` sau `-- python`. Ba trường hợp:
+- **Không thấy server `gemini-image`** → MCP chưa đăng ký. Đăng ký trỏ vào MCP entry của skill:
+  `claude mcp add --scope user gemini-image -- python "<.../skills/game-art/client/gemini_image_mcp.py>"`,
+  nhắc user `pip install -r client/requirements-client.txt` (máy khách) hoặc
+  `pip install -r server/requirements.txt` (node, có torch), rồi restart Claude Code.
+- **Có server, có đường dẫn** → kiểm bản đã có đủ tool chưa (mốc mới nhất là `upscale_image`):
+  ```bash
+  python -c "print('upscale_image' in open(r'<đường dẫn vừa đọc được>', encoding='utf-8').read())"
+  ```
+  `False` → server là bản CŨ (thiếu `upscale_image`, có khi thiếu cả `slice_sheet`/`process_raws`).
+  Trỏ lại registration vào `client/gemini_image_mcp.py` (bản đủ 12 tool), cài lại
+  requirements (client hoặc node), restart Claude Code, rồi dừng.
+- **Đọc được server nhưng không parse ra đường dẫn** (định dạng output đổi) → báo user, hỏi họ
+  chỉ thẳng đường dẫn file, đừng đoán.
+
+Không cần restart Claude Code chỉ để chạy skill nếu các tool `plan_asset`/`process_raws`/
+`slice_sheet`/`restyle_asset`/`make_compare_sheet`/`apply_asset` đã xuất hiện trong danh sách tool
+MCP. Nếu vừa cập nhật code mà tool chưa xuất hiện → phải restart Claude Code (MCP nạp tool
+lúc khởi động).
+
+*(Tự kiểm, không bắt buộc: `cd client && python test_imglib.py` — in `112/112 passed`; `python test_restyle_tools.py` — `0 failed`. Lớp mượn-node: `cd server && python test_remote.py` — `37/37 passed`. Chỉ chạy khi nghi ngờ code bị sửa hỏng.)*
+
+## Bước 1 — Style preset
+
+Kiểm `tools/restyle/styles/*.md`. Có rồi và user không đòi style mới → dùng luôn, sang bước 2.
+
+**Nếu user đưa ảnh mẫu** (`--style-ref`, hoặc paste ảnh, hoặc chỉ vào file):
+1. `plan_asset(<ref>)` → đọc field `palette` để lấy **hex chính xác**. Đừng đoán màu bằng mắt —
+   máy đọc chuẩn hơn. (`plan_asset` mở mọi ảnh RGBA, không chỉ asset game, nên dùng được cho ref.)
+2. Đọc ảnh mẫu bằng vision. Rút ra: chất liệu (đất sét / vector phẳng / pixel / màu nước / 3D bóng),
+   nét viền (có/không, dày bao nhiêu, màu gì), kiểu đổ bóng, hướng + độ gắt ánh sáng, độ chi tiết,
+   texture bề mặt, độ bo góc, tông cảm xúc.
+3. Ghép (1) + (2) → tự viết `tools/restyle/styles/<ten>.md`. Copy ảnh mẫu vào `styles/<ten>.refs/`.
+4. In tóm tắt cho user. Họ sửa câu nào thì sửa câu đó — **đừng bắt họ viết lại từ đầu**.
+
+**Nếu user không đưa ảnh mẫu**: hỏi tên style + hướng style, kèm 3–4 gợi ý cụ thể để chọn nhanh.
+
+**Nếu có cả hai**: phân tích ảnh trước, rồi apply yêu cầu chữ của user đè lên.
+
+Format `styles/<ten>.md`:
+
+```markdown
+# Style: <tên>
+
+## Mô tả một câu
+<một câu, đây chính là {STYLE_BLOCK} trong prompt>
+
+## Bảng màu
+- #RRGGBB — vai trò (nền / chủ đạo / nhấn / viền)
+
+## Chất liệu
+## Ánh sáng
+## Nét viền
+## Không được có (negative)
+## Màu key mặc định
+#00FF00  <!-- hoặc màu khác nếu asset xung đột; `plan_asset` quyết định cho từng asset -->
+```
+
+## Bước 2 — Anchor pass
+
+Chọn 1 asset đại diện (nhiều chi tiết, dễ nhìn ra style — hỏi user nếu không rõ; bỏ qua asset
+suy biến theo mục ở trên).
+
+1. `plan_asset(<asset>, avoid=[<bảng màu style preset>])` → lấy `key`, `width`, `height`, `bbox`,
+   `key_margin`, `key_safe`. Luôn truyền `avoid` bằng đúng các hex trong `## Bảng màu` của
+   `styles/<ten>.md` — `chroma_key` chạy trên ẢNH ĐÃ RESTYLE (palette style mới), không phải
+   palette asset gốc mà `plan_asset` tự đọc; bỏ qua `avoid` thì một style neon-xanh-lá trên asset
+   đỏ vẫn có thể khiến chọn nhầm xanh lá làm key.
+   `key_safe: false` → **cảnh báo user**: màu key nằm quá sát màu asset (margin dưới ngưỡng an
+   toàn của `chroma_key`), chính pixel chủ thể có nguy cơ bị gán alpha một phần → asset ra mờ như
+   bóng ma. `restyle_asset` sẽ bắt được ca này (flag `bad_translucent`), nhưng biết trước thì đỡ tốn
+   một lượt sinh.
+2. Dựng prompt theo `reference/prompt-template.md` (mục *Anchor pass*), nhét `{KEY_HEX}` = `key`
+   từ bước 1.
+3. Sinh ảnh thô theo mục "Sinh ảnh — backend" (mặc định **4 bản** từ backend đang sống;
+   cả hai sống + muốn so sánh chéo thì 2+2). **Cùng một prompt**, đầu vào ảnh =
+   `[<asset>, <=3 ref]` (tối đa 4 ảnh tính cả asset gốc — giới hạn chung cho
+   `generate_image` image_paths lẫn `codex --ref`). Ref nhiều hơn 3 → lấy 3 cái đầu,
+   **nói rõ cái nào bị bỏ**. Ảnh thô về `out/<ten>/_raw/`.
+4. Gọi `process_raws` **cho mỗi backend đã sinh** (prefix `"gem"` / `"gpt"` / `"v"` —
+   xem mục "Sau khi có ảnh thô") → `out/<ten>/…png`.
+5. Đọc `variants[]` trong dict trả về — mỗi variant có `flags` (list). Một bản có thể dính nhiều
+   flag cùng lúc. **Retry luôn bằng ĐÚNG backend đã sinh ra bản hỏng** (ảnh thô mới đánh số
+   tiếp, rồi `process_raws` lại TOÀN BỘ raw của backend đó):
+   - `bad_background` → nền không phẳng (`border_impurity` cao vì bóng/gradient/viền chưa key hết
+     ở vành ngoài, hoặc `coverage` > 0.95). **Trước khi flag này nổ, tool ĐÃ tự thử auto-key**
+     (đường chroma-key, key trượt cả khung → dò màu nền thật từ vành ảnh, key lại — thấy
+     `key_auto: true` nghĩa là đã được cứu, `key` là màu dò được, không cần làm gì). Vẫn flag
+     → sinh lại **1 lượt** backend đó, nhấn mạnh lại dòng `No cast shadow on the background` /
+     `No gradient` / `NOT a photographed studio backdrop` trong prompt. (BEN2 đang chạy thì
+     flag này gần như chỉ còn nghĩa `coverage` > 0.95 — segmentation trượt.)
+   - `bad_subject` → màu key ăn thủng chủ thể (`coverage` gần 0). `out: null`, không file nào ghi
+     ra — kiểm field `out`. Sinh lại **1 lượt** với `key` khác (đổi cả trong prompt lẫn tham số
+     `process_raws` — màu nền nằm trong ảnh thô nên PHẢI sinh lại, không chỉ process lại).
+   - `bad_translucent` → chủ thể ra mờ như bóng ma: `solid_ratio` thấp dù `coverage` bình thường
+     (màu key quá sát màu chủ thể, xem `key_margin` bước 1). Sinh lại **1 lượt với `key` khác** —
+     chọn ứng viên trong `KEY_CANDIDATES` (`#00FF00`, `#FF00FF`, `#00FFFF`, `#0000FF`) có margin
+     lớn hơn. **Sửa prompt KHÔNG cứu được ca này** — chỉ đổi màu key mới cứu.
+   - `sparse` / `bad_holes` → **THAM KHẢO, không phải lỗi, đừng retry vì hai flag này**. `sparse`
+     là chủ thể nhỏ nhưng đặc (icon/line-art mảnh — bình thường). `bad_holes` là có vùng trong
+     suốt đáng ngờ giữa chủ thể — có thể là lỗi key ăn thủng chi tiết, có thể là art hollow hợp lệ
+     (nhẫn, chữ "O"). Cứ ghi vào sheet, để mắt người quyết — đây chính là lý do sheet tồn tại.
+   - Vẫn hỏng sau 1 lần retry → **giữ nguyên trong sheet, ghi rõ flag/lý do, để user quyết** —
+     đừng tự ý loại bỏ khỏi sheet.
+   - `solid_ratio`, `border_impurity`, `hole_ratio` luôn có trong mỗi variant kể cả khi `flags`
+     rỗng (`ok`) — `solid_ratio` dưới ~0.5 (nhưng trên ngưỡng tự động 0.25) thì vẫn nên soi kỹ.
+   - `errors[]` không rỗng → có raw không đọc được (path sai/copy hỏng); `n_produced` cho biết
+     thực tế ra được mấy biến thể. (Đường fallback `restyle_asset` thì lỗi sinh nằm ở
+     `gen_errors` — xem "Khi hỏng".)
+6. **BẮT BUỘC — dựng file HTML đối chiếu** (kể cả khi chỉ 1 backend / chỉ vài variant).
+   Đừng lắp `groups` bằng tay: mỗi lần `process_raws`/`restyle_asset` đã trả sẵn
+   `compare_group`. Nhiều prefix (`gem`+`gpt`) → **GỘP `variants`** thành MỘT group cùng
+   `name`; chỉ 1 prefix → dùng group đó luôn:
+   ```
+   make_compare_sheet(
+     groups=[{"name": "<ten>", "original": "<asset gốc>",
+              "variants": [ ...mọi variant từ process_raws/restyle_asset... ]}],
+     out="tools/restyle/out/<ten>/compare.html")
+   ```
+   → bản gốc cạnh các biến thể, **nhấn giữ để lật về gốc**, đổi nền caro/sáng/tối, zoom.
+   (Không mở được trình duyệt thì fallback `make_contact_sheet(... out=".../sheet.png")`.)
+7. **Đưa đường dẫn `compare.html` cho user, để user chọn.** Không tự chọn hộ. Chưa gửi file
+   này thì lượt thiết kế CHƯA xong — **kể cả khi chỉ gen bằng GPT hoặc chỉ Gemini**.
+8. Bản được chọn → copy sang `tools/restyle/styles/<ten>.anchor.png`. Đây là **golden anchor**.
+   Ghi lại backend đã dùng — lần sau ưu tiên backend đó nếu vẫn healthy.
+
+## Bước 3 — Batch pass
+
+Từ đây anchor **thay thế** ref ngoài (anchor đã đúng chất asset game; ref ngoài chỉ là cảm hứng ban đầu).
+
+Với mỗi asset còn lại (đã lọc bỏ asset suy biến theo mục "Bỏ qua asset suy biến"):
+1. `plan_asset(<asset>, avoid=[<bảng màu style preset>])` → màu key **riêng cho asset đó** (asset
+   khác nhau, màu xung đột khác nhau). **Kiểm `key_safe` cho TỪNG asset ở đây, không chỉ ở anchor
+   pass** — anchor chỉ chứng minh style chọn được MỘT màu key an toàn cho MỘT asset; trong một lô
+   50+ asset hoàn toàn có thể có một asset xui bị `key_safe: false`. `key_safe: false` → ghi chú
+   lại, kỳ vọng flag `bad_translucent` cho asset đó, đừng bỏ qua.
+2. Sinh ảnh thô như anchor pass (backend đang sống, mặc định 4 bản; hoặc 2+2 nếu so sánh chéo)
+   với đầu vào `[<asset>, styles/<ten>.anchor.png]` và prompt batch
+   (`reference/prompt-template.md` mục *Batch pass*) → `_raw/…`, rồi `process_raws` theo
+   prefix có raw (`gem`/`gpt`/`v`, `src=<asset>`, `key=<key bước 1>`) → `out/<ten>/…png`.
+3. Đọc `variants[]` → cùng luật đọc `flags` và retry như bước 2 (retry bằng đúng backend hỏng;
+   `sparse`/`bad_holes` chỉ tham khảo, không retry vì hai flag đó).
+4. **BẮT BUỘC — gom 10 asset một lô → 1 file HTML đối chiếu** (`make_compare_sheet`, fallback
+   `make_contact_sheet`): **mỗi asset là MỘT group riêng, kèm `original` của chính nó**.
+   Gom mọi `compare_group` đã có (1 hoặc 2 prefix), **gộp theo `name`**:
+   ```
+   groups=[{"name":"coin","original":"<asset coin>","variants":[...các bản có được...]},
+           {"name":"button","original":"<asset button>","variants":[...]}, ...]
+   out="tools/restyle/out/_batch/compare_<lo>.html"
+   ```
+   Nhóm theo asset là điểm sống-chết của lô nhiều asset: dồn 40 ảnh vào một lưới phẳng thì
+   user phải tự nhớ ảnh nào của asset nào, và **không có bản gốc kèm bên cạnh thì không đối
+   chiếu được** — lệch tỉ lệ/hình dạng sẽ trôi qua. Đừng dồn hàng chục asset vào một trang.
+5. **Gửi đường dẫn file HTML đó cho user** rồi mới sang Bước 4.
+
+## Bước 4 — Apply
+
+Chỉ chạy sau khi user duyệt.
+
+```
+apply_asset(
+  variant="tools/restyle/out/<ten>/<gem|gpt><i>.png",   # v<i>.png nếu đi đường fallback
+  dst="<path/asset gốc trong project>.png",
+  backup_dir="tools/restyle/backup",
+  project_root="<gốc project, đường dẫn tuyệt đối>",
+)
+```
+
+`apply_asset` backup bằng cách **mirror đúng đường dẫn** của asset đích (tính từ `project_root`,
+không phải cwd lúc gọi) dưới `backup_dir` — nhờ vậy hai asset trùng tên nhưng khác thư mục không
+đè backup của nhau, và mirror path KHÔNG đổi dù được gọi từ đâu. **Luôn truyền `project_root`
+tường minh** (tuyệt đối) — thiếu nó, mirror phụ thuộc cwd và hai lần apply từ hai chỗ khác nhau
+có thể ra hai backup khác nhau cho CÙNG một asset.
+
+`apply_asset` cũng **không bao giờ ghi đè backup đã có** — lần apply thứ hai trở đi sẽ không nuốt
+mất bản gốc thật sự. Và nó **từ chối** (trả `{"error": ...}`, không ghi gì) nếu `backup_dir`/
+`project_root` khiến backup resolve trùng lên chính `dst`, hoặc nếu `variant`/`dst` không phải
+file `.png`.
+
+Xong thì báo user chạy game xem asset mới lên đúng chỗ, đúng size chưa.
+
+## Khi hỏng
+
+| Triệu chứng | Nguyên nhân | Xử lý |
+|---|---|---|
+| `codex_gen.sh` exit 3 | Thiếu `codex` hoặc không có python chạy được | Cài Codex CLI + `codex login`; script đã tự né stub `python3` của MS Store, nhưng máy phải có `python` thật |
+| `codex_gen.sh` exit 5 | `codex exec` hỏng — chưa `codex login`, mạng, hết quota ChatGPT | Chạy `codex login` rồi thử lại; vẫn hỏng thì đọc stderr tail script in ra |
+| `codex_gen.sh` exit 6/7 | imagegen không chạy hoặc không tìm thấy ảnh (đời codex đổi cơ chế lưu) | Kiểm `codex --version`; script đã hỗ trợ cả `generated_images/` (codex ≥0.145) lẫn session-scan (codex cũ) — đời mới hơn nữa thì sửa "Đường 1" trong script |
+| `generate_image` trả chuỗi bắt đầu bằng `Error:` | Tool này trả *chuỗi*, không phải dict — đừng đọc field `error` | Đọc phần sau `Error:`; cookie thì xem dòng cookie bên dưới, `No image URL` thì xem dòng kế |
+| Ảnh Gemini/`codex` ra ĐÚNG chủ thể nhưng nền không phải màu key | Backend bỏ qua dòng Output trong prompt | BEN2 vẫn tách được (không phụ thuộc màu nền); chỉ đường chroma-key fallback mới hỏng — soi sheet, cần thì sinh lại 1 lượt |
+| `gen_errors`/`generate_image` chứa `Redirected to consent page...` hoặc `Could not find any auth token...` hoặc `Session ĐĂNG XUẤT...` (đường Gemini web) | Cookie Gemini hết hạn (chặn HẲN backend A) | MCP **tự refresh** qua Chrome+CDP rồi thử lại — nếu vẫn báo lỗi thì profile cố định đã bị Google thu hồi: chạy `python server/refresh_gemini_cookies.py --login`, đăng nhập Gemini một lần, rồi `python server/refresh_gemini_cookies.py`. Chi tiết + bẫy scope cookie: `reference/mcp-image-input.md` § Cookie hết hạn |
+| `gen_errors` chứa `No image URL in response...` (đường Gemini web) | Prompt bị từ chối, hoặc model id/protocol Google đổi | Đổi prompt cho rõ hơn; nếu vẫn hỏng → `reference/mcp-image-input.md` § Khi protocol Google đổi |
+| variant có `key_auto: true` | Model vẽ nền lệch màu key (vd "xanh studio" `#2ED246` thay vì `#00FF00`) — tool đã tự dò màu nền thật từ vành ảnh và key lại thành công | **Không phải lỗi, không cần làm gì.** `key` trong variant là màu dò được, `key_requested` là màu ban đầu. Muốn giảm hẳn ca này: giữ dòng `NOT a photographed studio backdrop` trong prompt (đã có trong template) |
+| variant `flags` chứa `bad_background` ở mọi bản sinh | Model cứ đổ bóng/gradient lên nền, hoặc chưa key hết viền (auto-key chỉ cứu ca key trượt CẢ khung, không cứu nền bẩn một phần) | Nhấn mạnh lại `No cast shadow on the background` / `No gradient` / `NOT a photographed studio backdrop` trong prompt; hoặc bật BEN2 (không phụ thuộc màu nền) |
+| `bad_background` ở **mọi** bản sinh mà `bg_residue` = 0.0000 và `cutout_method` có vẻ ổn | Đây là ảnh NỀN tràn viền và bạn **quên `full_bleed=True`**. `border_impurity` giả định vành ảnh toàn là nền — sai với ảnh nền, nên nó đánh hỏng cả 4 bản tách nền hoàn hảo | Chạy lại `process_raws(..., full_bleed=True)`. Kiểm `impurity_gated` trong report: `true` = cửa đó đang phủ quyết |
+| Asset ra **mềm/nhoè** dù tách nền sạch | Bản sinh NHỎ hơn khung đích nên đã phải phóng to. Kiểm `upscale_method`: `lanczos` = không có `torch` nên rơi về nội suy; `esrgan` = đã dựng nét nhưng chi tiết là model ĐOÁN | Sinh lại nguồn TO hơn (đúng cách). Tạm thời: `pip install torch` để mở ứng viên esrgan. Xem `upscale_from`/`upscale_to` để biết đã phóng bao nhiêu |
+| `upscale_table` báo mọi ứng viên `disqualified` | `lr_err` > 30 (bản phóng mâu thuẫn ảnh nguồn) hoặc `cov_err` > 0.08 (matte bị phá) | Ảnh nguồn quá nhỏ so với đích — sinh lại, đừng phóng to |
+| variant `flags` chứa `bad_subject` | Màu key ăn thủng chủ thể; `out: null` | Sinh lại với `key` khác, ưu tiên ứng viên xa bảng màu asset gốc hơn (xem `key_margin` từ `plan_asset`) |
+| variant `flags` chứa `bad_translucent` | Màu key sát màu chủ thể → chủ thể bị bào thành bóng ma (`solid_ratio` thấp) | Đổi `key` sang ứng viên khác trong `KEY_CANDIDATES`. Xem `key_margin` TRƯỚC khi sinh — sửa prompt không cứu được |
+| variant `flags` chứa `sparse` | Chủ thể nhỏ (coverage thấp) nhưng ĐẶC (icon/line-art mảnh) | **KHÔNG phải lỗi, đừng retry.** Chỉ tham khảo — soi trong sheet như bình thường |
+| variant `flags` chứa `bad_holes` | Vùng trong suốt đáng ngờ GIỮA chủ thể (`hole_ratio` cao) — có thể key ăn thủng chi tiết, có thể art hollow hợp lệ (nhẫn, chữ "O", khung ảnh) | **THAM KHẢO, không phải gate cứng.** Nhìn sheet phân biệt; nếu đúng bị ăn thủng, retry như `bad_subject`/`bad_translucent` tuỳ mức độ |
+| `slice_sheet` ra `n_cells` ÍT hơn số chi tiết đã liệt kê | Model vẽ thiếu, hoặc hai chi tiết dính nhau thành 1 mảng liên thông | Soi sheet thô: thiếu → sinh lại 1 lượt; dính nhau → nhấn "space them WELL APART" trong prompt rồi sinh lại; hoặc bù chi tiết thiếu bằng luồng theo-asset |
+| `slice_sheet` ra `n_cells` NHIỀU hơn | Một chi tiết bị đứt gãy thành nhiều mảng (nét mảnh), hoặc model vẽ thừa | Ghép tay: cell đứt gãy thì tăng `pad`/giảm `min_cell` xem có liền lại không; thừa thì bỏ cell đó khi review |
+| `slice_sheet` cắt lẹm mockup vào dải chi tiết (hoặc ngược lại) | `mockup_frac` không khớp ranh giới model vẽ | Nhìn sheet thô, ước lại `mockup_frac` (model hay lệch khỏi 50%) rồi chạy lại — `slice_sheet` chỉ đọc, chạy lại không tốn lượt sinh |
+| Asset ra bị bóp méo | bbox gốc tỉ lệ khác hẳn chủ thể sinh ra | `fit_into` giữ tỉ lệ nên sẽ chừa lề — cân nhắc `size="WxH"` thay vì bám gốc |
+| Anchor pass tốt, batch trôi style | Anchor chưa đủ đặc trưng | Chọn anchor khác, nhiều chi tiết hơn |
+| Asset gốc chỉ 1-2px một chiều (vd 2×2048) | Đó là dải fill/gradient bị engine kéo giãn, không phải art | Bỏ qua, đừng đưa vào Gemini — xem "Bỏ qua asset suy biến" |
+| `apply_asset` trả `{"error": ...}` nhắc "trùng với chính asset đích" | `backup_dir`/`project_root` resolve backup trùng lên `dst` (vd `backup_dir="."` từ project root) | Đổi `backup_dir` sang thư mục KHÔNG chứa/trùng `dst` (vd `tools/restyle/backup`), luôn kèm `project_root` |
+| `apply_asset` trả `{"error": ...}` nhắc "phải là .png" | `variant` hoặc `dst` không có đuôi `.png` | Kiểm lại đường dẫn — `apply_asset` chỉ ghi đè file `.png` |