@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/reference/remote-lan.md

@@ -0,0 +1,224 @@
+# Cụm node trong LAN: mượn tài khoản sinh ảnh + GPU
+
+Một hoặc **nhiều máy (NODE)** có cookie Gemini, `codex login` và GPU. Các máy khác
+(**MÁY KHÁCH**) chạy skill bình thường nhưng mượn ba thứ đó qua mạng, và **tự chuyển node**
+khi node đang bận hoặc hết quota.
+
+> Đây là tài liệu KIẾN TRÚC (cả node lẫn máy khách, kèm lý do thiết kế). Nếu bạn chỉ cần
+> **cài và dùng một máy khách**, đọc `reference/client-guide.md` — ngắn hơn, theo từng bước.
+
+## Vì sao KHÔNG mở thẳng `gemini_image_mcp.py` ra mạng
+
+**11/12 tool của nó nhận đường dẫn file tuỳ ý** — đọc (`image_paths`, `raws`, `src`, `sheet`,
+`images`, `variant`) và **ghi** (`out_dir`, `out`, `dst`, `backup_dir`). `apply_asset` còn ghi
+đè file tại `dst` bất kỳ. Mở cổng cho nó = cấp cho mọi máy trong tầm quyền **đọc/ghi file tuỳ ý
+trên máy chủ**, không xác thực. Header của chính file đó đã cấm:
+
+> Server này CHỈ được chạy stdio local. KHÔNG tunnel/expose ra ngoài.
+
+`server/remote_host.py` là bản **đúng để expose**: **không một tham số đường dẫn nào**, ảnh đi
+qua mạng dưới dạng PNG base64 trong payload. Bất biến đó được khoá bằng test
+(`test_host_exposes_no_filesystem_parameter`) để sau này không ai vô tình thêm `out_dir` vào.
+
+Tệ nhất khi lộ token: người ta xài ké quota tài khoản bạn — **không** đụng được ổ đĩa.
+
+## Cái gì đi qua mạng, cái gì không
+
+Bốn seam cần tài khoản hoặc GPU đi qua mạng; **Gemini và Codex đối xứng nhau — cùng một
+server, cùng cụm, cùng bộ chọn node / quota / bận**:
+
+| Qua mạng (tool trên node) | Chạy tại MÁY KHÁCH |
+|---|---|
+| sinh ảnh **Gemini** (`gen_gemini`) | dò màu nền, unmix, chroma-key |
+| sinh ảnh **Codex** / GPT Image 2 (`gen_codex`) | **chấm điểm + chọn** cách tách nền |
+| BEN2 (`ben2_cutout`, một ứng viên tách nền) | loang màu, phóng alpha, **chấm điểm + chọn** cách phóng to |
+| Real-ESRGAN 4x (`esrgan_x4`, chỉ chạy model) | cắt bbox, bám size gốc, dựng sheet, ghi file |
+
+Hai đường sinh ảnh vào cụm theo hai lối khác nhau nhưng ĐÍCH giống hệt:
+- **Gemini** đi qua MCP: `restyle_asset`/`generate_image` → `_generate()` → node.
+- **Codex** đi qua bash: skill chạy `codex_gen.sh` → nó tự phát hiện `GAMEART_REMOTE_NODES`
+  → `remote_codex.py` → node. Máy khách KHÔNG cần `codex` CLI hay `codex login`.
+
+Cả hai đều qua cùng bộ `_call` chọn node: node rảnh nhất + còn quota trước, node báo bận/hết
+quota thì đổi ngay, hết node thì chờ 15 phút rồi báo. Codex có thêm ràng buộc **tuần tự trong
+mỗi node** (slot cố định 1) vì snapshot-diff session không an toàn khi song song — nhưng hai
+node khác nhau chạy codex song song được (mỗi node một phiên ChatGPT riêng).
+
+Ba hệ quả: máy khách **giữ quyền quyết định** (nó tự chấm điểm rồi tự chọn bản thắng); file của
+máy khách **không rời máy khách** trừ đúng ảnh cần model xử lý; 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 chạy đủ, pipeline **không chết**.
+
+## Cài — MÁY CHỦ (node)
+
+**1. Cấu hình.** Chép `server/.env.example` → `server/.env`, đặt token (và tuỳ chọn quota/cookie):
+
+```ini
+# server/.env
+GAMEART_REMOTE_TOKEN=<chuỗi ngẫu nhiên >= 16 ký tự — máy khách phải điền đúng token này>
+```
+
+Sinh token nhanh: `[guid]::NewGuid().ToString()+[guid]::NewGuid().ToString()`.
+
+**2. Chạy ngầm** — nháy đôi `server\start-node.cmd` (hoặc từ dòng lệnh):
+
+```
+server\start-node.cmd                 REM 0.0.0.0:8765, mọi card mạng
+server\start-node.cmd 0.0.0.0 9000    REM đổi cổng
+```
+
+Node chạy **ngầm** (đóng cửa sổ vẫn chạy), ghi log ra `server\node.log`, PID ra `server\node.pid`.
+Banner in ra địa chỉ để điền vào máy khách. **Dừng**: `server\stop-node.cmd`.
+
+- Chạy nền: lõi ở `node-ctl.ps1` (`-Action start|stop|status`).
+- Chạy foreground để xem log trực tiếp: `python server/remote_host.py --host 0.0.0.0 --port 8765`.
+- Linux/macOS: `server/start-node.sh` (foreground).
+
+Node **từ chối khởi động** nếu `server/.env` chưa có `GAMEART_REMOTE_TOKEN` (hoặc token < 16 ký tự) —
+mặc định "không mật khẩu" là cách người ta vô tình mở toang mọi thứ.
+
+Cần mở firewall Windows cho cổng đó (chỉ profile **Private**):
+
+```powershell
+New-NetFirewallRule -DisplayName "gameart-remote" -Direction Inbound `
+  -LocalPort 8765 -Protocol TCP -Action Allow -Profile Private
+```
+
+## Ship sang máy khác (bản nén)
+
+```bash
+python server/pack.py
+```
+
+Tạo cạnh thư mục skill:
+- **`game-art-client.zip`** → máy khách (không GPU). Giải nén → `game-art-client/`; MCP trỏ
+  `game-art-client/client/gemini_image_mcp.py`.
+- **`game-art-node.zip`** → node (có GPU). Giải nén → `game-art-node/`; chạy
+  `game-art-node/server/start-node.cmd`.
+
+Cả hai **KHÔNG** kèm `.env`/token, **KHÔNG** kèm `models/` (~1GB trọng số). Node **tự tải model
+khi khởi động** (nền, không chặn — request GPU đầu tiên không phải đợi download); các lần sau nạp
+từ cache. Tắt tự-tải bằng `GAMEART_WARMUP=0` (khi đó model tải lười ở request đầu).
+
+pack.py có **chốt an toàn**: quét mọi file text sắp nén, thấy GUID hoặc `*TOKEN=` giá trị thật
+(không phải placeholder) trong `.env*` thì **DỪNG** — chặn token lọt vào bản nén.
+
+Sau khi giải nén ở máy đích: chép `.env.example` → `.env`, điền token/địa chỉ.
+
+## Cài — MÁY KHÁCH (nhiều node)
+
+Chép `client/.env.example` → `client/.env` (hoặc đặt qua đăng ký MCP `claude mcp add ... -e KEY=VALUE`):
+
+```
+GAMEART_REMOTE_NODES = http://192.168.1.50:8765/mcp,http://192.168.1.51:8765/mcp
+GAMEART_REMOTE_TOKEN = <token dùng chung>
+```
+
+Mỗi node có thể mang token riêng — `http://192.168.1.51:8765/mcp|token-rieng-cua-no`. Một node
+thì `GAMEART_REMOTE_URL` như cũ vẫn chạy, không phải sửa gì.
+
+**Không đổi gì khác.** Tên tool giữ nguyên, dòng lệnh `codex_gen.sh` trong SKILL.md giữ nguyên
+từng chữ — script tự phát hiện `GAMEART_REMOTE_NODES` (hoặc `_URL`) rồi đẩy lượt sinh sang node.
+
+Máy khách chỉ cần `pillow`, `numpy`, `mcp`, `httpx`. **Không cần** torch, cookie Gemini, hay
+`codex login`.
+
+Kiểm bằng `auth_status()` — ở chế độ mượn máy nó trả `mode: "remote"`. Các cờ khả năng là của
+**CẢ CỤM**: một node có Gemini là cụm sinh ảnh được.
+
+```json
+{"mode":"remote","logged_in":true,"codex":true,"ben2":true,"esrgan":true,
+ "n_nodes":2,"n_alive":2}
+```
+
+Mọi tool sinh ảnh cũng trả thêm field `remote`; chi tiết từng node xem `remote_nodes()`.
+
+## Nhiều node: chọn, đổi, và chờ
+
+Máy khách tự chọn node theo **ba tầng**, mỗi tầng giải một bài khác nhau:
+
+1. **Xếp hạng trước khi gọi** — đọc `status` của mọi node (song song, timeout ngắn, cache 4s),
+   loại node đã kín chỗ / hết quota / không có khả năng cần dùng, rồi thử node **rảnh nhất**.
+   Cùng độ rảnh thì ưu tiên node **còn nhiều quota** — vắt kiệt một tài khoản là cách nhanh
+   nhất để bị khoá.
+2. **Đổi node khi bị từ chối** — node trả `busy` hoặc `exhausted` thì phạt riêng nó rồi
+   **chuyển ngay** sang node kế. Phạt "bận" ngắn (vài giây, nó sắp rảnh), phạt lỗi thật dài
+   (60s, đừng quay lại liên tục một node hỏng).
+3. **Hết node dùng được thì CHỜ** — ngủ tới lúc node sớm nhất hết phạt rồi thử lại, tối đa
+   `GAMEART_REMOTE_WAIT` (**mặc định 900s = 15 phút**). Quá hạn thì **báo lại kèm lý do của
+   từng node**, không im lặng chờ tiếp.
+
+Đây là lý do máy chủ **từ chối tức thì thay vì xếp hàng vô hạn**: node ngậm kết nối rồi mới xử
+lý sẽ tước mất quyền đổi node của máy khách — nó chỉ ngồi đợi đúng cái node đang tắc.
+
+Xem cả cụm bằng tool **`remote_nodes()`** (không tốn lượt sinh ảnh, không chạm GPU):
+
+```json
+{"enabled": true, "wait_budget_sec": 900, "nodes": [
+  {"url": "...:8765/mcp", "name": "node1",
+   "available": {"gemini": true, "codex": true, "ben2": true, "esrgan": true},
+   "slots": {"gpu": {"running": 1, "waiting": 0, "capacity": 1, "queue_max": 3, "load": 1.0}},
+   "quota": {"gemini": {"state": "ok", "used_hour": 12, "used_day": 84,
+                        "limit_hour": null, "cooldown_left": 0.0}}}]}
+```
+
+### Quota được biết bằng cách nào
+
+Cố ý **không bịa hạn mức**. Không ai biết chắc hạn mức thật của phiên web Gemini/ChatGPT, và
+một con số đoán sẽ khiến máy khách né một node vẫn còn dùng tốt. Chỉ có ba nguồn:
+
+| Trường | Nguồn |
+|---|---|
+| `used_hour` / `used_day` | **đo thật** — server tự đếm số lượt |
+| `limit_hour` / `limit_day` | **bạn tự khai** qua env, mặc định không biết (`null`) |
+| `state: exhausted` | **bằng chứng** — backend đã trả lỗi kiểu quota/429/rate-limit |
+
+`state`: `ok` → `limited` (chạm hạn mức bạn khai) → `exhausted` (backend báo hết). Một lượt
+**thành công** gỡ cờ `exhausted` ngay, không bắt node ngồi hết thời gian phạt.
+
+Khai hạn mức nếu bạn biết (trên MÁY CHỦ):
+
+```powershell
+$env:GAMEART_GEMINI_DAILY = "100"    # cũng có _HOURLY; tương tự GAMEART_CODEX_*
+$env:GAMEART_GEMINI_COOLDOWN = "1800" # giây nghỉ sau khi backend báo hết quota
+```
+
+### Sức chứa mỗi node
+
+| Env | Mặc định | Ghi chú |
+|---|---|---|
+| `GAMEART_GPU_CONC` / `GAMEART_GPU_QUEUE` | 1 / 3 | hai lượt ESRGAN 4096² song song là hết VRAM |
+| `GAMEART_REMOTE_GEMINI_CONC` / `GAMEART_GEMINI_QUEUE` | 2 / 4 | |
+| `GAMEART_CODEX_QUEUE` | 2 | sức chứa codex **cố định 1, đừng nâng** — snapshot-diff session không an toàn khi song song |
+| `GAMEART_CODEX_SCRIPT` | codex_gen.sh | script sinh codex (trên NODE). Đổi để dùng script sinh khác; giữ hợp đồng `--prompt/--out/--ref/--timeout-sec` |
+| `GAMEART_NODE_NAME` | hostname | tên hiện trong `remote_nodes()`, đặt tên dễ nhớ thì log mới đọc được |
+| `GAMEART_REMOTE_WAIT` (máy KHÁCH) | 900 | chờ tối đa khi mọi node bận |
+
+## Giới hạn & rủi ro — đọc trước khi dùng
+
+- **Chia sẻ MCP = chia sẻ tài khoản.** Mọi máy khách dùng CHUNG một tài khoản Google và một
+  phiên ChatGPT. Nhiều máy bắn vào một phiên web là đúng dấu hiệu hệ thống chống lạm dụng tìm.
+  **Dùng tài khoản phụ.** Rủi ro bị khoá là của người chạy máy chủ.
+- **Codex chạy TUẦN TỰ.** Nó móc ảnh bằng snapshot-diff `~/.codex/sessions/`; hai lượt cùng lúc
+  sẽ nhặt nhầm ảnh của nhau (header `codex_gen.sh` ghi rõ). Máy chủ tự xếp hàng bằng khoá — nên
+  nhiều máy khách cùng gọi codex sẽ **chờ nhau**, không phải chạy song song.
+- **GPU nối tiếp trong MỖI node** (mặc định 1 việc/lúc): hai lượt ESRGAN 4096² song song là
+  công thức hết VRAM. Muốn nhanh hơn thì **thêm node**, đừng nâng `GAMEART_GPU_CONC`.
+- **Token là mật khẩu chung, không phải định danh.** Nó chống máy lạ trong mạng, không phân biệt
+  được ai đang gọi và không thu hồi riêng từng máy được.
+- **Chỉ dành cho LAN tin cậy.** Không có HTTPS. Đưa ra Internet thì phải tự đặt sau reverse proxy
+  có TLS — server sẽ cảnh báo nếu `--host` không phải địa chỉ nội bộ.
+- **Ảnh lớn qua mạng tốn thời gian.** Trần mỗi ảnh 48MB (`GAMEART_REMOTE_MAX_BYTES`). Có GPU tại
+  chỗ thì skill **luôn ưu tiên chạy local**, chỉ mượn máy khi máy đó không có.
+
+## Khi hỏng
+
+| Triệu chứng | Nguyên nhân | Xử |
+|---|---|---|
+| `máy chủ từ chối token (401)` | token hai đầu lệch nhau | so lại `GAMEART_REMOTE_TOKEN`; nhớ là nó phân biệt hoa thường |
+| `ConnectError` / `ConnectTimeout` | máy chủ chưa chạy, sai IP/cổng, hoặc firewall chặn | kiểm `--host` là IP LAN (không phải 127.0.0.1) và luật firewall ở trên |
+| `auth_status` trả `logged_in: false` ở chế độ remote | máy CHỦ chưa có cookie Gemini | chạy `auth_status` **trên máy chủ** và xử theo mục cookie trong SKILL.md |
+| `ben2: false` / `esrgan: false` trong health | máy chủ thiếu torch | `pip install -r server/requirements.txt` **trên máy chủ** |
+| Máy chủ báo `Numpy is not available` | numpy 2.x làm gãy cầu nối với torch 2.4 | `pip install "numpy<2"` trên máy chủ. Xem chú thích trong `requirements.txt` |
+| `mọi node bận/không dùng được ... sau 15 phút chờ` | đúng như nó nói: cả cụm kẹt hoặc hết quota | đọc `remote_nodes()` xem node nào `exhausted` và `cooldown_left` còn bao lâu; thêm node, hoặc nâng `GAMEART_REMOTE_WAIT` |
+| Một node không bao giờ được chọn | `available` của nó báo `false` cho khả năng cần dùng | `remote_nodes()` cho biết vì sao: hết quota, kín chỗ, hay thiếu torch/codex trên node đó |
+| Mọi request treo tới timeout | đang chạy máy chủ trong script tự viết mà bắt `stdout=PIPE` rồi không đọc | ghi log ra FILE. Pipe đầy làm server **treo cứng** |

package/plugins/phaser-casual-game-factory/skills/pcgf-git-merge-request/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pcgf-git-merge-request
+description: Push Phaser Casual Game Factory (and installed game repos using this plugin) via a side branch, rebase onto main, and merge with a GitLab Merge Request. Use when the user asks to commit, push, rebase, merge request, MR, or land work on main — never push straight to main.
+---
+
+# PCGF Git push + Merge Request
+
+Do **not** push commits directly to `main` / `master`. Land work through a side branch + rebase + Merge Request.
+
+Remote for this factory:
+
+`git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git`
+
+Needs GitLab SSH (`ssh -T git@git.skylinkmedia.asia`). Use `glab` for MRs.
+
+## Required flow
+
+1. Fetch and start from latest main:
+
+```bash
+git fetch origin
+git checkout main
+git pull origin main
+git checkout -b <type>/<short-topic>
+```
+
+Branch names: `docs/...`, `fix/...`, `feat/...` (example: `docs/no-scaffold-install`).
+
+2. Commit only the intended files. Do not commit `tmp-*.png`, secrets, or `.env`.
+
+3. Rebase onto main **before** push:
+
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+Fix conflicts, then continue. Do not `rebase -i`. Never `--force` to `main`.
+
+4. Push the **side branch** only:
+
+```bash
+git push -u origin HEAD
+```
+
+5. Open a Merge Request into `main`:
+
+```bash
+glab mr create --source-branch <branch> --target-branch main --title "<title>" --description "<summary and test plan>"
+```
+
+Prefer the URL GitLab prints. Do not merge locally into `main` and push unless the user explicitly asks to skip the MR.
+
+6. Merge the MR when the user asks (or after they approve), **and delete the source branch**:
+
+```bash
+glab mr merge <id> --yes --rebase --remove-source-branch
+```
+
+7. Sync local main and drop the local side branch if it still exists:
+
+```bash
+git fetch origin --prune
+git checkout main
+git pull origin main
+git branch -d <branch>
+```
+
+If the remote branch remains after merge, delete it:
+
+```bash
+git push origin --delete <branch>
+```
+
+## Forbidden
+
+- `git push origin main` with new feature/docs commits
+- `--force` / `--force-with-lease` on `main`
+- Merging on the agent machine then pushing `main` as a substitute for an MR
+- Skipping rebase when the branch is behind `origin/main`
+- Leaving a merged side branch on the remote after a successful MR
+
+## After merge (other machines / games)
+
+Refresh installed plugin skills without overwriting game `src/`:
+
+```bash
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf install --yes --no-scaffold
+```
+
+Full wipe then reinstall:
+
+```bash
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf clean --yes
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf install --yes --scaffold
+```

package/plugins/phaser-casual-game-factory/skills/pcgf-ui-reskin/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: pcgf-ui-reskin
+description: >-
+  Navigate Phaser Casual Game Factory UI reskin work: audit theme / asset pack /
+  feeling / SFX gaps, present defaults vs options, apply chosen skills, then ship
+  a side-by-side compare.html before replacing production chrome. Triggers: reskin,
+  đổi UI, skin, theme pack, UI asset, feeling, button art, so sánh UI cũ mới,
+  compare UI. Search: ui reskin. Default theme theme-cream-casual; default assets
+  pack super-casual (use existing); create-new art via skill game-art; default
+  feeling phaser-ui-motion; default SFX phaser-ui-sfx.
+---
+
+# PCGF UI Reskin (navigator)
+
+Use this skill whenever the user asks to **reskin**, restyle, or upgrade product UI
+(theme CSS, bitmap chrome, press feeling, or UI SFX) on a game that **already has**
+UI. Do **not** use this skill for greenfield / new-project creation — that stays on
+**`phaser-casual-game-factory`** (apply cream / motion / sfx defaults directly).
+Do **not** jump straight into `phaser-ui-motion` alone for a full reskin — that is
+only the default **feeling** lane.
+
+Orchestrator skill **`phaser-casual-game-factory`** routes **existing-game** UI-skin
+work here; new games skip this navigator.
+
+## STOP — order of work
+
+1. **Audit** what is missing (theme / assets / feeling / SFX).
+2. **Present choices** (default highlighted) and wait for confirmation unless the user already named defaults.
+3. **Apply** the chosen skills / packs.
+4. **Build compare page** (`templates/ui-reskin/compare.html`) — old vs new.
+5. **Replace** production wiring only after the user accepts the compare page.
+
+Never overwrite live UI assets or CSS without a compare pass the user can open.
+
+## Registries (defaults + future options)
+
+Update these tables when new packs / skills land. Agents must offer **default** first.
+
+### Theme
+
+| Id | Skill | Default? | Notes |
+|----|-------|----------|-------|
+| `cream-casual` | **`theme-cream-casual`** | **yes** | CSS tokens + DOM press; not final bitmap art |
+| `dark-casual` | `theme-dark-casual` | no | Explicit opt-in only |
+
+### Assets
+
+| Mode | Default? | How |
+|------|----------|-----|
+| **Use existing pack** | **yes** | Copy from plugin `assets/ui-packs/<pack-id>/` into the game `public/assets/ui/` (map Button / Slider / Popup / …). |
+| **Create new** | no | Follow art skill below; output still reviewed via compare.html. |
+
+| Pack id | Path | Default pack? |
+|---------|------|---------------|
+| **`super-casual`** | Plugin `assets/ui-packs/super-casual/` (installed games: `_pcgf/plugin/assets/ui-packs/super-casual/`) | **yes** |
+| *(add more)* | `assets/ui-packs/<id>/` | no |
+
+| Art skill | Path / name | Default for create-new? |
+|-----------|-------------|-------------------------|
+| **`game-art`** | `skills/game-art/` | **yes** |
+| *(add more)* | `skills/<name>/` | no |
+
+### Feeling (interaction motion)
+
+| Id | Skill | Default? | Notes |
+|----|-------|----------|-------|
+| **`ui-motion`** | **`phaser-ui-motion`** | **yes** | Buttons / popups / sliders; press-until-release + off-canvas window up |
+| *(add more)* | future feeling skills | no | May rename skill folders later; keep this registry as the source of truth |
+
+### SFX (UI audio)
+
+| Id | Skill | Default? | Notes |
+|----|-------|----------|-------|
+| **`ui-sfx`** | **`phaser-ui-sfx`** | **yes** | Click / close contract + default MP3s in `assets/sfx/` |
+| *(add more)* | future SFX generators / packs | no | Create/replace sounds here — **not** inside feeling skills |
+
+Feeling skills **call** SFX APIs; they must not own sound file creation.
+
+## Audit checklist
+
+Run against the target game (or demo) and report gaps:
+
+| Lane | OK when | Gap when |
+|------|---------|----------|
+| Theme | `factory-cream-casual.css` imported + `body.factory-page` + `bindFactoryDomPress` (or explicit other theme) | Competing hand-rolled colors / purple-on-navy default |
+| Assets | Bitmap chrome from a registered pack (or game art) wired for buttons/sliders/popups as needed | Cream CSS only, or random one-off PNGs with no pack |
+| Feeling | Interactive controls use the chosen feeling skill (`bindButtonMotion` / …) | Ad-hoc tweens / stuck press |
+| SFX | `playUiClick` / `playUiClose` via **`phaser-ui-sfx`**, files under `/assets/sfx/` | Silent UI or SFX logic buried only in motion |
+
+Present results as:
+
+```text
+Reskin audit
+- Theme:   OK | NEED — recommendation: cream-casual (default)
+- Assets:  OK | NEED — recommendation: use pack super-casual (default) | create via game-art
+- Feeling: OK | NEED — recommendation: phaser-ui-motion (default)
+- SFX:     OK | NEED — recommendation: phaser-ui-sfx (default)
+```
+
+Then ask (or confirm if already answered):
+
+1. Theme — default `theme-cream-casual` or option?
+2. Assets — default **use existing** `super-casual`, or **create new** with `game-art`?
+3. Feeling — default `phaser-ui-motion` or option?
+4. SFX — default `phaser-ui-sfx` (keep / refresh default MP3s) or create new via that skill?
+
+## Apply
+
+| Choice | Do |
+|--------|----|
+| Theme cream | Follow **`theme-cream-casual`** |
+| Theme dark | Follow **`theme-dark-casual`** only if chosen |
+| Assets use pack | Copy selected files from `assets/ui-packs/super-casual/` (or other pack) → game `public/assets/ui/…`; wire CSS/`load.image` |
+| Assets create | Follow **`game-art`** (compare.html from that skill still required) |
+| Feeling | Follow **`phaser-ui-motion`** (or chosen feeling skill) |
+| SFX | Follow **`phaser-ui-sfx`**; copy `assets/sfx/ui_*.mp3` into game public if missing |
+
+## Compare page (mandatory before replace)
+
+1. Copy `templates/ui-reskin/compare.html` into the game (e.g. `public/ui-reskin-compare.html` or `tmp/ui-reskin-compare.html`).
+2. Fill **Before** / **After** panels (screenshots, `<img>` of old vs new chrome, or iframes).
+3. Open the page for the user.
+4. Only after explicit approval: swap production asset paths / CSS / wiring to the After set.
+5. Keep the compare file until the user says to delete it.
+
+`game-art` already produces its own compare.html for generated bitmaps — still produce or link a **product UI** compare when theme/feeling/SFX also changed.
+
+## NEVER / ALWAYS
+
+| ALWAYS | NEVER |
+|--------|-------|
+| Start from this navigator for reskin | Jump only to `phaser-ui-motion` for a full reskin |
+| Offer defaults from the registries | Invent a parallel theme/motion/SFX stack |
+| Ship compare.html before replace | Overwrite production UI silently |
+| Keep SFX in **`phaser-ui-sfx`** | Re-bury sound authorship inside feeling skills |
+| Extend registries when adding packs/skills | Hard-code a second undocumented default |
+
+## Related skills
+
+- Theme: `theme-cream-casual`, `theme-dark-casual`
+- Feeling: `phaser-ui-motion`
+- SFX: `phaser-ui-sfx`
+- Create art: `game-art`
+- Factory orchestrator: `phaser-casual-game-factory`

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

@@ -0,0 +1,33 @@
+---
+name: phaser-adaptive-loading
+description: "Implement adaptive Phaser loading for config, player data, current-level recovery, and idle next-level preloading based on device capacity. Use for data/asset load scheduling and scene-safe background preload; not for a cosmetic loading bar alone."
+---
+
+# Phaser Adaptive Loading
+
+Use `templates/adaptive-loading/` alongside the existing `LoadingManager` UI contract. Detect a `DeviceProfile` once at boot; do not repeatedly benchmark during gameplay.
+
+- Tiers: `potato` / `low` / `mid` / `high`. Default concurrency: potato/low 1, mid 2, high 4.
+- Treat `saveData`, low RAM/cores, slow benchmark, and slow connection as low/potato. Keep profile thresholds configurable and do not rely on browser information alone.
+- Detect once via `detectDeviceProfile` / `DeviceTierSession.create()`. Feed `AdaptiveLoadingManager` the **effective** profile.
+- QA force (demo only): skill **`tool-demo-qa`** — `DeviceTierSession` + `bindDemoDeviceTier` (`?tier=potato`, `localStorage.pcgf.demo.deviceTier`). On override call `manager.setProfile(effective)` and update Perf HUD tier label. Official builds stay auto-detect; tools-off removes the force UI.
+- Queue next-level data/assets through `scheduleNextLevel()`. Its activity source must report both input and animation state; preloading begins only after the configured uninterrupted idle window.
+- Queue remaining current-level data before next-level data with `scheduleRemainingCurrentLevel()`. Mark assets required for immediate spawn/render as `requiredNow`; they bypass the idle gate and take priority, as in Association Match commit `22693f6`.
+- Separate `memoryPressure` from `decodePressure`. High memory pressure lowers mandatory next-level preload (default 35%) to avoid eviction/OOM; high decode pressure with adequate memory raises it (default 85%) to prevent gameplay hitch. The percent refers only to mandatory entry assets, never all level assets.
+- Cancel the scheduled preload on scene shutdown, level change, logout, or a new target level. Pass AbortSignal to fetch/decode work and make tasks safe to abandon.
+- Preloading is opportunistic: failure must never block the active level. The normal transition still performs required loading behind the existing loading overlay.
+
+## Loading view
+
+Use `templates/loading-view/` only for loads that need visible blocking/transition: first boot assets, scene changes, and mandatory level entry. Background current/next-level queues default to no view.
+
+For visible loads, follow `skills/phaser-loading-view` and `references/loading-view.md`:
+
+- ViewModel owns real tasks/progress and independent open/minimum/close timing.
+- View owns background, mask, slider and tween presentation.
+- Home↔Game / Next Level hole: cover **full → 0**, reveal **0 → full**.
+- Pause BitmapMask while fully covered (HUD dwell); resume before reveal.
+- Progress paint dirty-check **Δ ≥ 1%** (do not redraw the bar every frame).
+- Feed mandatory adaptive-load work into the same weighted `LoadingViewModel`.
+- Start work during opening; never use a fake View-side progress ticker.
+- Keep idle prefetch failures non-blocking. A later mandatory entry load still reports its real remaining work.