@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/skills/adspro-to-superads/SKILL.md

@@ -1,9 +1,10 @@
 ---
 schema: 1
 name: adspro-to-superads
-description: Use when migrating an Android app from AdsPro (com.android.fullhd.adssdk:AdsPro, AdsSDK, Admob*) to SuperAds (com.android.fullhd.ads:SuperAds, Ads.show). Deterministic procedure — JSON-first, wrapper-first, minimal-diff.
-version: 1.2.0
+description: Use when migrating an Android app from AdsPro (AdsSDK, Admob*) to SuperAds (Ads.show) - JSON-first, wrapper-first
+version: 1.3.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # AdsPro → SuperAds
@@ -11,94 +12,61 @@ group: Ads
 Đây là **deterministic migration procedure**, không phải tài liệu giới thiệu SuperAds. Mọi chỗ
 agent có thể "sáng tạo" đều bị khoá bằng contract, invariant hoặc stop condition.
 
-Đọc `references/` khi đến phase tương ứng — đừng đoán API.
-
-| Phase | File |
-|---|---|
-| 0 + 3 | [references/migration-pitfalls.md](references/migration-pitfalls.md) — bẫy SDK + cách **đo app đang migrate** (không copy số liệu app khác) |
-| 3 — config | [references/config-template.md](references/config-template.md) |
-| 4 — wrapper | [references/wrapper-template.md](references/wrapper-template.md) |
-| 3 + 5 — map API | [references/api-mapping.md](references/api-mapping.md) |
-| fail runtime | [references/troubleshooting.md](references/troubleshooting.md) |
-| sau Phase 7 | [references/verification.md](references/verification.md) |
-
 ## When to use
 
 Dùng skill này khi app đang phụ thuộc `com.android.fullhd.adssdk:AdsPro` (entry `AdsSDK` +
 `Admob*`) và cần chuyển sang SuperAds (`object Ads`, config 3 tầng `units / adItems / placements`).
 
-## When NOT to use
+## 🚫 When NOT to use
 
 - App đã dùng SuperAds — đây không phải skill thêm placement mới (dùng `super-ads-add-placement`).
 - Sửa bug SuperAds core, thêm network plugin, hay đổi schema JSON của SDK.
 - App không có AdsPro (không có `AdsSDK.init`, không có `AdmobInter` / `AdmobNative`).
 
-## Authority Order
-
-Khi các nguồn xung đột, thứ tự thẩm quyền:
-
-1. Source SuperAds hiện tại (`super-ads/src/main/.../api/`, `domain/config/key/AdConfigKey.kt`, `core/flow/`)
-2. Migration production của SlideShow — **cho API và JSON**, không cho chiến lược diff
-3. Source AdsPro
-4. Template / example trong skill này
-5. Suy luận của agent
-
-Không dùng example/template trong skill để suy ra API nếu source thực tế khác. **Không được tự
-suy luận nếu source chưa chứng minh.** Không copy `showEvery`, số native chain, countdown, RC
-key, hay `mode.navigate` từ SlideShow / app đã migrate khác — đo app hiện tại.
-
-## Ba nguyên tắc
+## 📋 Prerequisites
 
-Thứ tự khi xung đột: **JSON-first > wrapper-first > minimal-diff**. Giữ diff nhỏ không bao giờ
-là lý do để giữ behavior trong Kotlin.
+- Định tuyến skill và kiểm version SDK: [super-ads-guide](../super-ads-guide/SKILL.md).
+- Skill này nhắm SuperAds `>=4.0.0 <5.0.0`. Nếu app đang dùng SuperAds thấp hơn, **dừng** và khuyến nghị
+  (không ép) nâng cấp bằng [super-ads-upgrade](../super-ads-upgrade/SKILL.md) trước khi tiếp tục.
+- App phụ thuộc AdsPro (`com.android.fullhd.adssdk:AdsPro`), repo git để tạo checkpoint `migration/*`
+  (rollback phải biết điểm trở về).
+- Truy cập repo SuperAds artifacts `http://repo.volio.vn/repository/maven-s3/` (chi tiết trong
+  [phase-1-2-gradle-manifest.md](references/phase-1-2-gradle-manifest.md)).
+- Đã đọc [migration-pitfalls.md](references/migration-pitfalls.md): đo **app này**, không copy số liệu app khác.
 
-### 1. JSON-first
+## ⚡ Quick Reference
 
-Một dòng behavior mà JSON diễn đạt được thì **không được tồn tại trong Kotlin**. Ba ví dụ điển
-hình (bảng đầy đủ behavior → key JSON, theo từng tầng `adItems`/`placements`/`wrapper`: xem
-[references/config-template.md](references/config-template.md) §"Key theo tầng" và
-[references/api-mapping.md](references/api-mapping.md)):
-
-| Behavior | Kotlin cũ (AdsPro) | JSON mới |
-|---|---|---|
-| preload theo thời điểm | `AdmobX.load(space)` rải rác | `preload.eventActive` |
-| gate "chỉ show khi đã load" | `getStatusBySpace == LOADED` | `mode.show: SHOW_LOADED` |
-| auto reload chu kỳ | timer trong Fragment | `reload.auto.placementID` + `show.timeAutoReloadMs` |
+Đọc file tương ứng khi đến phase đó — đừng đoán API.
 
-Code smell sau migration — còn thấy là chưa xong: `Handler`/`delay` quanh ads, biến `countShowAd`,
-`System.currentTimeMillis()` so khoảng cách ad, `Ads.preload*` thủ công, `if (status == LOADED)`
-trước show, `R.layout.*` trong **thân wrapper**, timer reload trong Fragment.
-
-### 2. Wrapper-first
-
-**Giữ vỏ, bỏ ruột.** Hàm gọi ad gốc của app được giữ **nguyên chữ ký** và trở thành lớp wrapper
-mỏng delegate xuống `Ads.show`. Behavior bên trong bị bỏ hết vì đã sang JSON. Màn hình **không bị
-sửa** nếu chữ ký giữ được.
-
-Giữ chữ ký ≠ port behavior. Điều bị cấm là mang *logic* cũ sang, không phải mang *tên hàm* sang.
-
-Một số tham số trở thành **inert** (`idLayoutAds`, `layoutLoadingRes`, `forceLoadNew`, …). Rủi
-ro: sau này có người đổi `R.layout.x` ở call site và không có gì xảy ra. Xử lý:
-
-- Mỗi tham số inert ghi vào bảng "Inert parameters" trong `migration-inventory.md`.
-- Trong thân wrapper có **một** dòng comment nêu tham số đó giờ do JSON quyết định.
-- Dọn tham số inert là **commit riêng sau migration**, không nằm trong phạm vi này.
-
-### 3. Minimal-diff
-
-- Không tạo file utils mới nếu đã có nhà. File `AdsUtils.kt` (hoặc tương đương) cũ được **giữ lại
-  làm nhà cho wrapper** — moi ruột, giữ path và tên. Giữ path nghĩa là ~40 màn hình không đổi
-  một dòng `import`.
-- Một file wrapper duy nhất. Không tách `NativeAdsHelper` / `InterAdsHelper`.
-- Không sửa màn hình nếu wrapper giữ được chữ ký. Mỗi lần sửa màn hình phải có lý do thuộc đúng
-  danh sách Phase 5b.
-- Code mới (`EventScreen`, hook base fragment) ưu tiên thêm vào file đã có trong package base.
-- Mục tiêu diff: `≈ 1 file config JSON + 1 file wrapper + 1 file base + n màn hình có lý do 5b`.
-  Không phải 40 màn hình.
-
-SlideShow (commit `4e36e791`) tạo `AdsSP.kt` mới và comment bỏ 650 dòng `AdsUtils.kt`, sửa ~158
-file. Skill dùng SlideShow làm authority cho **API và JSON**, nhưng **không** copy chiến lược
-diff của nó.
+| Cần gì | Mở file |
+|---|---|
+| Bẫy SDK + cách đo app đang migrate (phase 0 + 3) | [references/migration-pitfalls.md](references/migration-pitfalls.md) |
+| Map API AdsPro → SuperAds, bảng `adsType` → `format` (phase 3 + 5) | [references/api-mapping.md](references/api-mapping.md) |
+| Mẫu config JSON, key theo tầng, referential integrity (phase 3) | [references/config-template.md](references/config-template.md) |
+| Mẫu wrapper `AdsUtils.kt` + `EventScreen` (phase 4) | [references/wrapper-template.md](references/wrapper-template.md) |
+| Authority order, ba nguyên tắc, diff budget | [references/principles-and-authority.md](references/principles-and-authority.md) |
+| Contract MUST / MUST NOT, Stop Conditions | [references/migration-contract.md](references/migration-contract.md) |
+| Câu hỏi nhóm A-D phải hỏi user | [references/user-questions.md](references/user-questions.md) |
+| Phase 0: checkpoint, inventory, verify | [references/phase-0-inventory.md](references/phase-0-inventory.md) |
+| Bảng A-D, Decisions, Inert, Exclusions (mẫu) | [templates/migration-inventory.md](templates/migration-inventory.md) |
+| Phase 1-2: Gradle, Manifest | [references/phase-1-2-gradle-manifest.md](references/phase-1-2-gradle-manifest.md) |
+| Phase 3: 3a-3g config | [references/phase-3-config-migration.md](references/phase-3-config-migration.md) |
+| Phase 4: wrapper, EventScreen, observability | [references/phase-4-wrapper-observability.md](references/phase-4-wrapper-observability.md) |
+| Phase 5-7: call site, layout, cleanup | [references/phase-5-7-callsites-layout-cleanup.md](references/phase-5-7-callsites-layout-cleanup.md) |
+| Global Invariant Check + 13 chuỗi `adType` | [references/global-invariant-check.md](references/global-invariant-check.md) |
+| Runtime fail | [references/troubleshooting.md](references/troubleshooting.md) |
+| Verify sau Phase 7 | [references/verification.md](references/verification.md) |
+| API `Ads.*` tra nhanh | [snippets/ads-api-quick.md](snippets/ads-api-quick.md) |
+
+## 🏗️ Recommended Architecture
+
+Thứ tự khi xung đột: **JSON-first > wrapper-first > minimal-diff**. Giữ diff nhỏ không bao giờ là lý do
+để giữ behavior trong Kotlin. Chi tiết và authority order:
+[principles-and-authority.md](references/principles-and-authority.md).
+
+- **JSON-first** — behavior mà JSON diễn đạt được thì không được tồn tại trong Kotlin.
+- **Wrapper-first** — giữ vỏ, bỏ ruột: hàm gọi ad gốc giữ nguyên chữ ký, delegate xuống `Ads.show`.
+- **Minimal-diff** — mục tiêu `≈ 1 file config JSON + 1 file wrapper + 1 file base + n màn hình có lý do 5b`.
 
 ```text
 AdsPro:     40 màn  --space + R.layout + timing-->  AdsUtils (650 dòng)  --> Admob*.load/show
@@ -107,666 +75,69 @@ SuperAds:   40 màn KHÔNG ĐỔI --chữ ký cũ-->  AdsUtils moi ruột  --> A
                                               JSON (format, layout, mode, preload, reload, chain)
 ```
 
-## Migration Contract
-
-MUST:
-
-- Placement name giữ **nguyên văn** spaceName cũ, kể cả sai chính tả
-  (`Native_Trennding`, `Native_Litst_Face_Filter`, `Native_WellcomeBack`).
-  **MUST NOT CHANGE.** Dashboard doanh thu, Firebase RC và analytics đang query đúng chuỗi đó.
-- `adsType` preserve đúng format semantics theo bảng trong `references/api-mapping.md`.
-- Mediation adapter `com.google.ads.mediation:*` hiện có **giữ nguyên**.
-- App open setup **đúng một lần** trong wrapper `init`.
-- Firebase RC key ads giữ nguyên chuỗi.
-- Mỗi thời điểm preload cũ ứng **đúng một** màn/thời điểm trong `preload.eventActive` (một chuỗi,
-  hoặc cặp `_fo` + `_fn` của **cùng** thời điểm nếu code cũ preload vô điều kiện — xem 3b).
-- Consent (CMP) **trước** mọi preload / show / app open: wrapper chỉ dispatch event và mở app open
-  sau callback `showCmp` (`MIGRATION.md:126-127` — core không tự chặn request khi chưa có consent).
-- `mode.navigate` theo **từng** placement, đọc callback AdsPro của **app này**. Default SDK `NAVIGATE_ON_DISMISS` — không copy template/SlideShow.
-- Reload → `reload.*` trên `placements`. Layout + unit là của **placement đích** (`ReloadCoordinator`). Bảng D khi có click reload.
-- File JSON migrate **trùng** `Ads.init` / `configProvider` của app này.
-- Nếu có native-sau-inter: `firstShowAt` / `showEvery` / `adItems.native[]` đo từ counter + số dialog **production của app này** (công thức SDK `ChainAdActivity`), không copy app khác / không đếm space JSON.
-- Hàm gọi ad gốc **giữ nguyên chữ ký**; wrapper ở đúng file cũ.
-- Nối đủ ba mối observability trước khi verify: logger sink, tracker collector, config provider.
-
-MUST NOT:
-
-- Đổi / chuẩn hoá / sửa chính tả placement name.
-- Tạo abstraction mới, hay tách wrapper thành nhiều file helper.
-- Port *logic* của `AdsUtils.kt` cũ (chữ ký thì giữ).
-- Xoá mediation adapter vì "SuperAds đã có sẵn".
-- Gọi `Ads.preload*` thủ công thay `preload.eventActive`.
-- Tự viết timer / listener reload ở app — `ReloadCoordinator` trong core đã làm.
-- Sửa màn hình khi không có lý do thuộc danh sách Phase 5b.
-- Dọn tham số inert trong cùng commit migration.
-- Tạo `LegacyAdCallbackAdapter` hay bất kỳ lớp ép 14 callback AdsPro thành 7 callback SuperAds.
-- Gán `mode.navigate` hàng loạt từ template / default SDK.
-- Gộp nhiều layout click khác nhau vào một adItem reload (P2) — hoặc tách bừa khi AdsPro đã tách space.
-- `adItems.native[]` / `showEvery` copy từ template hoặc từ app đã migrate khác.
-- Reload đích = space zero call site chỉ vì tên có `Reload`.
-- Sửa JSON A trong khi init / RC đọc JSON B.
-
-## Stop Conditions
-
-Agent **dừng và hỏi user** (theo catalog bên dưới), không đoán, khi:
-
-- Gặp API AdsPro không có trong bảng mapping.
-- Placement không có format mapping xác định.
-- Thiếu module provider SuperAds cho network trong config.
-- Callback semantics không thể bảo toàn.
-- Config có placement trùng tên.
-- Không xác định được hành vi của RC key ads.
-- Call site `load()` không xác định được ứng với screen event nào.
-- App chưa có `screenName()` hoặc registry tracking screen.
-- AdItem `NATIVE_COLLAPSIBLE` không đủ cặp layout collapsed + expanded.
-- Không xác định được code cũ nav từ callback show hay dismiss.
-- Click reload: cùng space AdsPro nhưng **khác** layout / unit — không biết tách bao nhiêu target (P2).
-- Flag RC / AB / counter ads không diễn đạt được bằng một JSON tĩnh (P4).
-- Reload cũ không xác định được trigger là click, dismiss hay timer.
-- Wrapper không thể giữ chữ ký cũ (hàm cũ trả về giá trị SuperAds không cung cấp).
-
-## Câu hỏi phải hỏi user
-
-Mỗi câu hỏi phải có **phương án khuyến nghị** và nêu **hệ quả**. Agent không được tự chọn thay
-user ở nhóm A và B. Gộp câu hỏi cùng nhóm vào **một** lần hỏi.
-
-- Nhóm B: hỏi khi lập inventory Phase 0.
-- Nhóm A và D: hỏi **trước** Phase 3.
-- Nhóm C: hỏi **một lần** đầu Phase 4.
-
-Mọi câu trả lời ghi vào mục "Decisions" trong `migration-inventory.md`.
-
-### Nhóm A — tính năng không chuyển được (loại C)
-
-| Tình huống | Câu hỏi | Phương án gợi ý |
-|---|---|---|
-| App dùng `AdmobNativePip` | SuperAds không có native PIP. Xử lý placement này thế nào? | (1) Bỏ PIP, chuyển thành `NATIVE` thường ở cùng vị trí — khuyến nghị; (2) Giữ AdsPro riêng cho PIP — không khuyến nghị, hai SDK cùng tồn tại; (3) Tạm tắt placement |
-| App dùng `AdmobNativeCollapsibleHalfSize` | Không có half-size. Dùng gì thay? | (1) `NATIVE_COLLAPSIBLE` với layout expanded nhỏ hơn — khuyến nghị; (2) Bỏ, dùng `NATIVE` |
-| Space có `adsType` không nằm trong bảng map | `adsType` này không có format tương ứng. Ý định sản phẩm là gì? | Liệt kê 2–3 format gần nhất kèm khác biệt hành vi |
-
-### Nhóm B — behavior không suy ra được từ code
-
-| Tình huống | Câu hỏi | Phương án gợi ý |
-|---|---|---|
-| Code cũ nav ở cả hai callback, hoặc nav ngoài callback | Placement này nav khi ad *hiện* hay khi ad *đóng*? | Mặc định SDK là `NAVIGATE_ON_DISMISS`; nêu hệ quả UX từng lựa chọn |
-| `load()` gọi trong `onCreate` của Activity, không thuộc màn nào | Preload này nên gắn với event màn nào? | Đề xuất màn gần nhất trong flow + phương án preload ngay sau init |
-| Không rõ preload áp cho phiên nào | Preload cho người mở lần đầu, người quay lại, hay cả hai? | Khuyến nghị **cả hai** (`_fo` + `_fn`) nếu code cũ preload vô điều kiện |
-| Reload cũ vừa có timer vừa có click | Giữ cả `reload.auto` và `reload.click`, hay chỉ một? | Chain chỉ nhận click |
-| Space trong JSON nhưng zero call site (vd `Banner_chung`) | Giữ placement này hay bỏ? | (1) Giữ, ghi vào Documented exclusions — khuyến nghị (an toàn cho RC); (2) Bỏ khỏi config |
-| Hai space khác nhau nhưng cùng ý nghĩa | Gộp hay giữ tách? | Khuyến nghị **giữ tách** để bảo toàn analytics |
-| Event cũ mang `previous_screen`/`next_screen` trong bundle | Event khai trong JSON không mang được cặp screen. Bỏ cặp screen, hay giữ tracking app-side? | (1) Bỏ, dùng `adItemId` — khuyến nghị; (2) Collect `TrackerEvent.Impression` rồi tự ghép screen từ state app |
-| Tên event analytics cũ rải rác trong Kotlin | Tên nào đưa vào `tracking.event*`, tên nào giữ app-side? | Event AB/theo placement vào JSON; event bespoke cần ngữ cảnh app thì giữ trên flow |
-
-### Nhóm C — quyết định kiến trúc (đầu Phase 4)
-
-| Câu hỏi | Phương án gợi ý |
-|---|---|
-| Nhà cho wrapper: moi ruột `AdsUtils.kt` cũ, hay tạo `AdsSP.kt` mới? | (1) Moi ruột file cũ — **khuyến nghị**, giữ path nên ~40 màn không đổi import; (2) File mới kiểu SlideShow — sạch tên nhưng phải sửa import ở mọi màn |
-| Nhà cho `EventScreen`: thêm vào file base có sẵn hay tạo file mới? | (1) Thêm vào file base sẵn có; (2) File mới `EventScreen.kt` nếu package base không có nhà hợp lý |
-| Có dọn tham số inert trong migration không? | Khuyến nghị **không** — tách commit riêng sau khi verify xong |
-| Config: một file JSON asset, hay thêm nhánh Remote Config ngay? | Khuyến nghị asset trước, RC sau khi verify |
-
-### Nhóm D — hạ tầng (hỏi ngay khi phát hiện)
-
-| Tình huống | Câu hỏi |
-|---|---|
-| Config có network nhưng thiếu module | Config có `"network": "CloudX"` nhưng chưa có `SuperAdsCloudX`. Thêm module hay bỏ network khỏi config? |
-| Thiếu `io.cloudx.APP_KEY` / `applovin.sdk.key` | Cung cấp key, hay bỏ network đó? |
-| App chưa có `screenName()` / registry tracking | Không có gì dựng chuỗi event preload. Wire tracking screen trước, hay preload theo cách khác? |
-| App có RC key timing ads (tên tuỳ app, vd `keyTimeBetweenAdInter`) | JSON chỉ có `show.timeBetweenMs` cố định. Ops còn chỉnh nóng qua RC không? |
-| Có native-sau-inter | Production: mấy native/lần inter? RC/AB nào (nếu có) tắt native phụ? Counter `% N` ra pos nào? Điền JSON theo đo, không theo template |
-| Click reload cùng space, khác layout | Tách twin SuperAds theo Bảng D, chung unit nếu AdsPro chung `ids[]` |
-| `minimumFetchIntervalInSeconds` | SlideShow đặt `0` (fetch mọi lần). Giữ `0` hay đặt giá trị an toàn hơn cho production? |
-| App đã có AppsFlyer / Adjust / Meta | Giữ nguyên kênh nào? `SuperAdsTracking` là **mặc định nên có** (Phase 1) — thiếu nó là mất `ad_impression` / `ad_click` Firebase (`MIGRATION.md:452`). Chỉ bỏ khi app tự bắn doanh thu Firebase ở chỗ khác và user xác nhận |
-
-## Checkpoint git
-
-Trước Phase 1, tạo checkpoint và **luôn biết mình đang ở checkpoint nào**. Không bắt buộc commit
-tự động — nhưng rollback phải biết điểm trở về.
-
-| Checkpoint | Khi nào |
-|---|---|
-| `migration/00-inventory` | Sau khi `migration-inventory.md` đầy đủ |
-| `migration/01-gradle` | Sau Phase 1 |
-| `migration/02-manifest` | Sau Phase 2 |
-| `migration/03-config` | Sau Phase 3 |
-| `migration/04-wrapper` | Sau Phase 4 |
-| `migration/05-call-sites` | Sau Phase 5 |
-| `migration/06-layout` | Sau Phase 6 |
-| `migration/07-cleanup` | Sau Phase 7, trước Global Invariant Check |
-
----
-
-## Phase 0 — Inventory matrix (artifact bắt buộc)
-
-Tạo file `migration-inventory.md` trong repo **app** trước khi sửa dòng code nào. Không có file
-này thì không được sang Phase 1.
-
-Nguồn: `rg -l "com.android.fullhd.adssdk"`, `rg -n "\.load\("`, mọi `spaceName` trong
-`assets/*.json`, layout native XML + view id, RC key ads.
-
-### Bảng A — placement identity + behavior
-
-| spaceName | adsType | ids[] | layout collapsed | layout expanded | show API cũ | nav từ callback nào | reload trigger cũ | space reload cũ | RC key | placement | format | mode.show | mode.navigate | status |
-|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
-| Native_Home | native | 1 | native_collap_small | - | show | - | click | Native_Reload | config_ads_22_4 | Native_Home | NATIVE | LOAD_AND_SHOW | - | TODO |
-| Interstitial_Chung | interstitial | 1 | - | - | show + gate LOADED | onAdDismissed | - | - | config_ads_22_4 | Interstitial_Chung | INTER | SHOW_LOADED | NAVIGATE_ON_DISMISS | TODO |
-
-Cột `placement` = nguyên văn `spaceName`. **MUST NOT CHANGE.**
-
-### Bảng B — preload moment (một hàng mỗi call site `load()`)
-
-| File:line | space | màn đang đứng | screenName() | thời điểm | chuỗi event | status |
-|---|---|---|---|---|---|---|
-| LanguageFragment.kt:45 | Native_Onboarding | Language | open_screen_1 | onViewReady | create_open_screen_1_fo | TODO |
-
-Không gom nhiều `load()` của cùng space thành một hàng. Mỗi thời điểm là một hàng.
-
-### Bảng C — cặp reload
-
-| placement nguồn | trigger | placement đích | chu kỳ (ms) | key JSON | status |
-|---|---|---|---|---|---|
-| Native_Home | click | Native_Reload | - | reload.click.placementID | TODO |
-| Native_Record_Video | auto | Native_Record_Video_ReLoad_15s | 15000 | reload.auto.placementID + show.timeAutoReloadMs | TODO |
-
-### Bảng D — click reload theo layout (khi app có click reload)
-
-Bảng C gom trigger. Bảng D vì SDK bind layout trên **adItem đích**. Hàng mẫu chỉ hiểu cột —
-điền space/layout/unit **của app này**. Tách twin **chỉ khi** layout hoặc unit lúc click khác nhau.
-
-| nguồn | layout lúc show | unit AdsPro lúc click | SuperAds reload placement | unit | layout đích | self-click? |
-|---|---|---|---|---|---|---|
-| *(space)* | *(xml)* | *(ids click)* | *(space reload cũ hoặc twin mới)* | *(khớp AdsPro)* | *(= layout show)* | *(click lại cùng space?)* |
-
-Space reload **zero call site** → Exclusions, không làm đích vì tên.
-
-### Các mục khác trong cùng file
-
-- **Decisions** — câu trả lời nhóm A/B/C/D.
-- **Inert parameters** — tham số giữ chữ ký nhưng không còn tác dụng.
-- **Documented exclusions** — space được giữ / bỏ có lý do (vd `Banner_chung` zero call site).
-
-### Verify Phase 0
-
-- [ ] Mọi hàng có `status`
-- [ ] Không hàng nào trống `format`
-- [ ] Số hàng Bảng B = số call site `load()` đếm được
-- [ ] Mọi space reload **có call site** xuất hiện ở Bảng C
-- [ ] Nếu có click reload: Bảng D; layout/unit đích khớp AdsPro lúc click
-- [ ] Đã đọc [migration-pitfalls.md](references/migration-pitfalls.md) — đo **app này**, không copy số liệu app khác
-- [ ] Nhóm câu hỏi B đã hỏi và ghi vào Decisions
-- [ ] Checkpoint `migration/00-inventory`
-
----
-
-## Phase 1 — Gradle
-
-Bỏ:
-
-```gradle
-implementation 'com.android.fullhd.adssdk:AdsPro:...'
-```
-
-Thêm (phiên bản hiện tại của core và mọi plugin: `4.0.0` — `super-ads/build.gradle:6`,
-`MIGRATION.md:7-15`; **đọc lại source / maven hiện tại, không hardcode từ skill nếu source khác**):
-
-```gradle
-def superAds = '4.0.0'   // core + MỌI plugin cùng một version (SPI đổi package ở 4.0.0 — trộn 3.x là NoClassDefFoundError lúc chạy)
-implementation "com.android.fullhd.ads:SuperAds:$superAds"
-// Bộ nền: LUÔN khai (kể cả config chưa có unit InHouse)
-implementation "com.android.fullhd.ads:SuperAdsInHouse:$superAds"
-implementation "com.android.fullhd.ads:SuperAdsDebug:$superAds"             // có cả ở release
-debugImplementation "com.android.fullhd.ads:SuperAdsDebugOverride:$superAds" // chỉ debug, không lọt release
-implementation "com.android.fullhd.ads:SuperAdsAdmob:$superAds"     // BẮT BUỘC nếu config có network Admob (kéo theo SuperAdsUmp)
-implementation "com.android.fullhd.ads:SuperAdsTracking:$superAds"  // ad_impression / ad_click Firebase — thiếu là mất doanh thu
-implementation 'com.android.fullhd.layout:SuperAdsLayout:1.0.0-alpha27'
-
-// Chỉ thêm khi config có network tương ứng:
-implementation "com.android.fullhd.ads:SuperAdsCloudX:$superAds"
-implementation "com.android.fullhd.ads:SuperAdsApplovin:$superAds"
-```
-
-Wrapper (Phase 4) viết theo API 4.0.0 (vd `com.android.fullhd.super_ads.api.lifecycle.AppLifecycleMonitor`,
-`MIGRATION.md:26`). Pin bản 3.x trở xuống thì wrapper không compile.
-
-`SuperAdsTracking` tự cài qua `TrackingInstaller` (ContentProvider), không gọi code. Thiếu module ⇒
-**mất `ad_impression` (doanh thu) và `ad_click`** dù config bật (`MIGRATION.md:452`). Cờ bật/tắt là
-key phẳng trong `global`: `"global": { "tracking.revenue": true }` (mặc định `true`,
-`SA/domain/config/model/AdsConfig.kt:85`).
-
-**Thiếu `SuperAdsAdmob` = zero ads im lặng, không crash.** `ConfigRegistryCheck` log
-`ERROR_AND_CRASH` lúc init — chỉ thấy được nếu đã nối logger sink (Phase 4).
-
-Giữ nguyên mọi `com.google.ads.mediation:*` hiện có. CloudX adapter (`io.cloudx:adapter-*`) chỉ
-thêm khi user chọn dùng CloudX (nhóm D).
-
-Repo SuperAds artifacts: `http://repo.volio.vn/repository/maven-s3/` (`allowInsecureProtocol = true`).
-
-Kiểm version **trước khi khai** (mỗi artifact sẽ dùng, `<A>` = `SuperAds`, `SuperAdsAdmob`, `SuperAdsUmp`, `SuperAdsTracking`…):
-
-```bash
-curl -sL https://repo.volio.vn/repository/maven-s3/com/android/fullhd/ads/<A>/maven-metadata.xml | grep -o "<version>[^<]*</version>"
-```
-
-Trạng thái đã kiểm ngày 2026-10-27: repo có `4.0.0` của cả 11 artifact SDK (`SuperAds`, `SuperAdsAdmob`, `SuperAdsAdmobNextGen`, `SuperAdsApplovin`, `SuperAdsArbiter`, `SuperAdsCloudX`, `SuperAdsInHouse`, `SuperAdsTracking`, `SuperAdsUmp`, `SuperAdsDebug`, `SuperAdsDebugOverride`); `SuperAdsContract:1.0.0-alpha` đã có. Trạng thái đổi theo thời gian: luôn chạy lệnh trên, đừng tin con số này. Version cần dùng chưa có trên repo ⇒ Stop, hỏi user: chờ nhóm SDK publish (`scripts/publish-modules.sh --remote`, script đã gồm `ump` và `admob-next-gen`), hay dùng tạm `mavenLocal` / project dependency. Không tự hạ xuống bản cũ: wrapper và config theo API 4.0.0.
-
-### Verify Phase 1
-
-- [ ] `./gradlew :app:dependencies --configuration releaseRuntimeClasspath` thấy `SuperAds`,
-      `SuperAdsAdmob`, `SuperAdsTracking` cùng `4.0.0`, và **không còn** `AdsPro`
-- [ ] Mediation adapter cũ vẫn còn
-- [ ] Checkpoint `migration/01-gradle`
-
----
-
-## Phase 2 — Manifest
-
-Giữ:
-
-```xml
-<meta-data
-    android:name="com.google.android.gms.ads.APPLICATION_ID"
-    android:value="@string/admob_app_id" />
-```
-
-Thêm **chỉ khi** config có network tương ứng:
-
-```xml
-<meta-data android:name="io.cloudx.APP_KEY" android:value="..." />
-<meta-data android:name="applovin.sdk.key" android:value="..." />
-```
-
-Không khai activity / provider ads thủ công — mỗi module SuperAds tự register bằng
-`ContentProvider` (`AdmobInstaller`, `InHouseInstaller`, `CloudXInstaller`, `AppLovinInstaller`).
-
-### Verify Phase 2
-
-- [ ] AdMob APPLICATION_ID còn
-- [ ] Key CloudX / AppLovin khớp quyết định nhóm D
-- [ ] Checkpoint `migration/02-manifest`
-
----
-
-## Phase 3 — Config migration
-
-Đọc [references/config-template.md](references/config-template.md),
-[references/api-mapping.md](references/api-mapping.md) và
-[references/migration-pitfalls.md](references/migration-pitfalls.md) **trước** khi viết JSON. Hỏi
-nhóm A và D nếu chưa hỏi.
-
-Bảy bảng con 3a–3g + Bảng D. Cập nhật cột `status` của Bảng A/B/C/D khi xong từng hàng.
-
-### 3a — Identity
-
-- 1 `spaceName` → 1 `placement` **giữ nguyên tên**.
-- `ids[]` (waterfall high-floor) → nhiều `units` entry, **giữ đúng thứ tự** trong `adItem.units[]`.
-- `adsType` → `format` theo bảng 15 giá trị. Không map được → stop, hỏi nhóm A.
-
-### 3b — Preload: từ `load()` sang event
-
-```text
-BaseFragment.onCreate     -> EventScreen.pushEventCreateScreen(screenName())
-BaseFragment.onDestroy    -> EventScreen.pushEventDestroyScreen(screenName())
-     -> emit "create_{screenName}_{fo|fn}" / "destroy_{screenName}_{fo|fn}"
-     -> setUpPreloadTrigger() collect -> Ads.waitAdSDKReady { Ads.dispatchEvent(activity, event) }
-     -> khớp "preload.eventActive" của adItem -> preload
-```
-
-SlideShow gọi `pushEventCreateScreen` trong `onCreate`, `pushEventDestroyScreen` trong
-`onDestroy` — không phải `onViewCreated` / `onDestroyView`. Khớp source app đang migrate, không
-đoán lifecycle.
-
-- Chuỗi event là **convention của app**, không phải hằng số SDK. JSON khớp **từng ký tự**; lệch
-  một ký tự là **im lặng không preload**, không log lỗi.
-- `_fo` / `_fn` (first-open / quay lại) là **hai chuỗi khác nhau**. Code cũ preload vô điều kiện
-  thì khai **cả hai**, như SlideShow: `["create_open_screen_5_fo", "create_open_screen_5_fn"]`.
-- Chỉ màn **đã hook** `pushEventCreateScreen` mới emit (Activity thường sót). `isFo` nếu
-  `lazy` thì lock lần đầu. Event = màn **đang đứng** lúc `load()`, không đoán màn kế.
-- Key thuộc tầng **`adItems`**; đặt lên `placements` bị bỏ qua.
-- `preload.enabled` default **true** (`AdItemConfig.isPreloadEnabled()`). Lật false trên adItem
-  `SHOW_LOADED` giết âm thầm placement vì cache luôn rỗng.
-- Key phụ: `preload.max`, `preload.delayLoadFistMs` (đúng chính tả source — `Fist` không phải
-  `First`), `preload.delayLoadAfterShowMs`, `preload.autoPreloadAfterDismiss`.
-- Mỗi hàng Bảng B → một chuỗi thêm vào `preload.eventActive` của adItem tương ứng.
-- **Không** thay `load()` bằng `Ads.preload.preloadNow` (API thủ công, đã `@Deprecated` —
-  `SA/api/AdsFeatures.kt:90`).
-
-Phase 3b và Phase 4 khớp nhau **qua chuỗi event** — coupling duy nhất được phép.
-
-### 3c — Layout
-
-- Native / banner thường: **một** key `ui.layoutAdName.{network}`.
-- Collapsible (`NATIVE_COLLAPSIBLE`): **hai** key —
-  `ui.layoutAdName.{network}` = **collapsed / small**,
-  `ui.layoutAdNameExpand.{network}` = **expanded / large**.
-- Từ AdsPro: `AdmobNativeCollapsible.show(..., layoutRes, collapsibleLayoutRes, ...)` →
-  `layoutRes` vào key thường, `collapsibleLayoutRes` vào key Expand.
-  **Đảo hai cái thì ad vẫn fill, vẫn có impression, build vẫn pass, chỉ hiện sai cỡ.**
-- Suffix network **chữ thường, phân biệt hoa thường**: `.admob`, `.cloudx`, `.applovin`, `.meta`.
-  AdItem trộn network phải khai key cho **từng** network, thiếu là `RenderError.LayoutNotFound`.
-- Giá trị là **tên file XML không đuôi**, resolve trong res app hoặc `SuperAdsLayout`.
-- Loading: `ui.loading.layoutName` + `ui.loading.enable`.
-- `NativeConfig(resNativeMeta)` (layout riêng khi mediation AdMob trả về Meta) → **loại B**:
-  `ui.layoutAdName.meta` (+ `ui.layoutAdNameExpand.meta` cho collapsible). Plugin AdMob chọn layout
-  meta khi response là Meta mediation và file XML tồn tại, ngược lại dùng layout thường
-  (`SA/presentation/render/NativeRenderer.kt:97`, `SA/presentation/render/CollapsibleNativeRenderer.kt:80`;
-  `super-ads-admob/src/main/java/com/android/fullhd/super_ads/plugin/admob/nativead/NativeLayoutResolver.kt:40`). `meta` chỉ là **hậu tố key**, không phải
-  network — không khai unit `"network": "Meta"` (`SA/domain/config/key/AdConfigKey.kt:42`).
-- **Một** `ui.layoutAdName` / adItem / network. AdsPro xoay `index % N` layout → P5, hỏi product.
-- Native full chain: XML app **hoặc** catalog SuperAdsLayout — product chọn, ghi Decisions. Không tự coi lệch XML là bug, cũng không mặc định catalog.
-
-### 3d — Chuyển màn: theo behavior thật của app
-
-- `mode.show`: `LOAD_AND_SHOW` (default) ứng `loadAndShow(...)`; `SHOW_LOADED` ứng `show(...)`
-  **có gate `getStatusBySpace == LOADED`**. Vì vậy `getStatusBySpace` làm gate là loại **B**.
-- `mode.navigate`: chỉ `NAVIGATE_ON_SHOW` / `NAVIGATE_ON_DISMISS`. Default
-  `NAVIGATE_ON_DISMISS` (`AdItemConfig.getModeNavigate()`; giá trị lạ bị ép về default).
-  Xác định **bắt buộc đọc từ app**: nav trong `onAdShowedFullScreenContent` → `NAVIGATE_ON_SHOW`;
-  trong `onAdDismissedFullScreenContent` → `NAVIGATE_ON_DISMISS`. Không suy ra được thì hỏi nhóm B.
-- Sau migration app **vẫn sở hữu nav đi đâu** qua `NavAdCallback`, chỉ không còn sở hữu *thời điểm*.
-- Không áp một `mode.navigate` chung. Splash / leftover / in-app / chain đo riêng (P1).
-- Placement chain: một giá trị không cover hai path AdsPro (nav lúc show vs lúc đóng native). Ghi Decisions nếu lệch.
-
-### 3e — Reload: đưa hết vào `placements`
-
-SDK tự chạy — `ReloadCoordinator.Plan.from(placement, surface)` trong core đọc config. App
-**không viết một dòng reload nào**. Wrapper **không** có hàm reload. SlideShow từng viết
-`showAdViewWithReload` rồi comment bỏ toàn bộ — đó là bằng chứng, không phải code cần copy.
-
-| Trigger | Key | Timing kèm theo |
-|---|---|---|
-| click vào ad | `reload.click.placementID` | - |
-| đóng ad (collapsible dismiss) | `reload.dismiss.placementID` | `show.timeDelayShowAfterDismissMs` |
-| chu kỳ tự động | `reload.auto.placementID` | `show.timeAutoReloadMs` |
-
-Mẫu chuẩn: cặp placement sinh đôi `X` / `X_Reload`, khớp họ space `*_Reload` của app cũ.
+## Workflow
+
+Mỗi phase kết thúc bằng mục "Verify Phase N" và một checkpoint `migration/NN-*`
+(bảng checkpoint: [phase-0-inventory.md](references/phase-0-inventory.md)).
+
+1. **Chốt contract.** Đọc [migration-contract.md](references/migration-contract.md) (MUST / MUST NOT,
+   Stop Conditions). Gặp stop condition thì dừng và hỏi user, không đoán.
+2. **Hỏi user theo nhóm.** [user-questions.md](references/user-questions.md): nhóm B khi lập inventory
+   Phase 0; nhóm A và D trước Phase 3; nhóm C một lần đầu Phase 4. Mọi câu trả lời ghi vào "Decisions".
+3. **Phase 0 — Inventory.** Tạo `migration-inventory.md` trong repo **app** (Bảng A/B/C/D) từ
+   [templates/migration-inventory.md](templates/migration-inventory.md) trước khi sửa dòng code nào.
+   Quy trình: [phase-0-inventory.md](references/phase-0-inventory.md).
+4. **Phase 1 — Gradle.** Bỏ `AdsPro`, thêm core + mọi plugin cùng một version `4.0.0`, giữ mediation
+   adapter. Kiểm version trên maven trước khi khai.
+   [phase-1-2-gradle-manifest.md](references/phase-1-2-gradle-manifest.md).
+5. **Phase 2 — Manifest.** Giữ AdMob `APPLICATION_ID`; chỉ thêm key CloudX / AppLovin khi config có
+   network đó; không khai activity / provider ads thủ công.
+   [phase-1-2-gradle-manifest.md](references/phase-1-2-gradle-manifest.md).
+6. **Phase 3 — Config JSON** (3a identity, 3b preload, 3c layout, 3d chuyển màn, 3e reload, 3f analytics,
+   3g native sau inter). Đọc [config-template.md](references/config-template.md),
+   [api-mapping.md](references/api-mapping.md), [migration-pitfalls.md](references/migration-pitfalls.md)
+   trước khi viết JSON. Chi tiết: [phase-3-config-migration.md](references/phase-3-config-migration.md).
+7. **Phase 4 — Wrapper + EventScreen + observability.** Mặc định moi ruột `AdsUtils.kt` cũ, giữ path và
+   chữ ký; nối đủ logger sink, tracker collector, config provider; consent trước preload / app open.
+   Mẫu: [wrapper-template.md](references/wrapper-template.md); chi tiết:
+   [phase-4-wrapper-observability.md](references/phase-4-wrapper-observability.md).
+8. **Phase 5 — Call sites.** 5a: không sửa màn hình nếu wrapper giữ được chữ ký. 5b: chỉ sửa màn hình khi
+   có lý do trong danh sách đóng. [phase-5-7-callsites-layout-cleanup.md](references/phase-5-7-callsites-layout-cleanup.md).
+9. **Phase 6 — Layout.** Id badge `ivAdMark` → `tvAdMark`, bỏ `R.layout.*` khỏi thân wrapper, mọi
+   `ui.layoutAdName*` có file XML thật. Cùng file ở bước 8.
+10. **Phase 7 — Cleanup.** Xoá dialog ads tự viết và timer đã bị JSON thay thế; không xoá wrapper, không
+    dọn tham số inert (commit riêng). Cùng file ở bước 8.
+11. **Global Invariant Check** sau Phase 7, **trước** build:
+    [global-invariant-check.md](references/global-invariant-check.md).
+12. **Verify runtime** theo [verification.md](references/verification.md); gặp lỗi xem
+    [troubleshooting.md](references/troubleshooting.md).
+
+## 🔧 API Reference
+
+Ba ví dụ điển hình "JSON-first" (bảng đầy đủ behavior → key JSON theo tầng `adItems` / `placements` /
+`wrapper`: [config-template.md](references/config-template.md) §"Key theo tầng" và
+[api-mapping.md](references/api-mapping.md)):
 
-Layout + unit thuộc **đích**. Gộp / tách theo Bảng D của **app này** (P2) — không hardcode một twin hay N twin. Click lại cùng space AdsPro → self-click trên twin. Chain: `reload.click` trên placement chain.
-
-`ConfigRegistryCheck` log issue lúc init (key vẫn bị bỏ qua, không crash):
-
-- `show.timeAutoReloadMs` mà **thiếu** `reload.auto.placementID` ⇒ auto-reload **không chạy**.
-- Placement gốc INTER / REWARD / APP_OPEN mang `reload.*` ⇒ bỏ qua (không có container để thay tại
-  chỗ, `SA/config/validate/ConfigRegistryCheck.kt:182`).
-- Placement đích không tồn tại / tắt / priority rỗng / **khác loại bề mặt** với gốc ⇒ bỏ qua
-  (`SA/config/validate/ConfigRegistryCheck.kt:202`).
-- Placement **chain** không nhận `reload.auto` (tự advance slot, timer tranh render).
-- Placement **chain** không nhận `reload.dismiss` (đóng slot = sang bước kế). Chain chỉ reload bằng click.
-
-Ngoài `ConfigRegistryCheck`:
-
-- Chu kỳ auto bị `ReloadCoordinator` kẹp sàn `MIN_AUTO_RELOAD_MS = 5_000L`
-  (`SA/show/ReloadCoordinator.kt:23`, `SA/show/ReloadCoordinator.kt:82`).
-- Key `reload.placementID` (thiếu `.click` / `.dismiss` / `.auto`) **không tồn tại** trong
-  `AdConfigKey.Reload` — có trong config demo nhưng **vô hiệu**, SDK không báo gì. Không được dùng.
-
-### 3f — Analytics: tên event vào JSON
-
-| Key (tầng `adItems`) | Bắn khi | Tương ứng AdsPro |
+| Behavior | Kotlin cũ (AdsPro) | JSON mới |
 |---|---|---|
-| `tracking.eventImpress` | impression | `onAdImpression` + `logPairValue*` |
-| `tracking.eventLoaded` | load xong | `onAdLoaded` |
-| `tracking.eventPaid` | paid event | `onAdPaidValueListener` |
-| `tracking.mode` | `ALWAYS` / `ONCE_PER_PROCESS` / `ONCE_PER_LIFETIME` | `Set` chống trùng tự viết |
-
-Giá trị là **mảng** tên event. Event bắn ra `TrackerEvent.TrackingEvent` trên `Ads.tracker.events`;
-app forward sang Firebase / Meta ở **một** chỗ trong wrapper.
-
-Doanh thu tự động: artifact `com.android.fullhd.ads:SuperAdsTracking` (Phase 1; tự cài khi có
-dependency, không gọi code; bật/tắt bằng key phẳng `tracking.enable` / `tracking.revenue` /
-`tracking.perf` / `tracking.arbiter` trong object `global`) và
-`Ads.tracking.enableAppsflyer(app, appsflyerId)` — thay `pushAppsflyerRevenue` thủ công.
-
-Event JSON **không mang** được cặp `previous_screen` / `next_screen`. Hỏi nhóm B.
-
-`global.version` là nhãn để soi config nào đang chạy (Toast `UpdateJson`). Bump version mỗi lần
-sửa JSON để Toast chứng minh file đang chạy (O1).
-
-### 3g — Native sau inter (`INTERSTITIAL_NATIVE_CHAIN`)
-
-Chỉ khi **app này** có dialog / flow native sau inter. Công thức SDK:
-`nextPos >= firstShowAt && (nextPos - firstShowAt) % showEvery == 0`.
-Điền số từ counter AdsPro của app — template `1`/`2`/`5000` / 1–2 native **không** phải chuẩn sản phẩm.
-
-- `adItems.native[]` = số native production (kèm RC/AB **tên key của app này**), không = số space JSON.
-- Countdown = timer dialog app này.
-- `reload.click` trên placement chain. Xoá dialog Kotlin song song (Phase 5b).
-- adItem chain `SHOW_LOADED` cần cache: `preload.enabled` (mặc định true) **không** được tắt và phải
-  có `preload.eventActive`. Tắt preload thì không preload, không vào event map, nhánh `SHOW_LOADED`
-  luôn `ModeShowedButNotHaveAdCached` ⇒ placement không bao giờ show
-  (`SA/engine/load/Preloader.kt:225`, `SA/config/repository/AdsConfigRepositoryImpl.kt:180`, `SA/engine/load/PriorityLoader.kt:163`).
-  Không preload được thì dùng `LOAD_AND_SHOW`.
-
-`forceLoadNewAdIfShowed` **không** suy ra `mode.show`. Đọc `show` vs `loadAndShow` + gate `LOADED`.
-
-### Verify Phase 3
-
-- [ ] Checklist referential integrity trong `config-template.md` pass
-- [ ] Cột `status` Bảng A/B/C cập nhật; nếu có click reload thì Bảng D layout/unit khớp AdsPro
-- [ ] `Ads.init` / RC khớp file JSON vừa viết (P0)
-- [ ] Nếu có chain: `adItems.native` + gate khớp đo Phase 0 của **app này**
-- [ ] Checkpoint `migration/03-config`
-
----
-
-## Phase 4 — Wrapper + EventScreen + observability
-
-Hỏi nhóm C trước. Mặc định khuyến nghị: **moi ruột file `AdsUtils.kt` cũ**, giữ path, giữ chữ ký
-mọi hàm public, thay ruột bằng delegate xuống `Ads.show`.
-
-Đọc [references/wrapper-template.md](references/wrapper-template.md).
-
-Bề mặt cần có: `init / setPremium / isPremium / showCmp / setUpAppOpen / setUpPreloadTrigger /
-dispatcherEvent` + 4 extension `showAdView`, `showAdFull`, `showAdFullInApp`, `showAdRewardFull`
-(extension có thể private nội bộ file nếu màn hình vẫn gọi chữ ký cũ).
-
-`EventScreen`: `MutableSharedFlow` replay 0, extraBufferCapacity 64. Hook base fragment:
-`onCreate` → `pushEventCreateScreen(screenName())`, `onDestroy` →
-`pushEventDestroyScreen(screenName())`. Collector của `EventScreen` phải subscribe **trước** màn đầu
-emit (replay 0 ⇒ emit khi chưa có subscriber là mất): launch bằng `Dispatchers.Main.immediate`.
-
-**Consent trước preload / app open.** Core không tự chặn request khi chưa có consent
-(`MIGRATION.md:126-127`). Wrapper giữ cờ `consentDone`: `showCmp` set cờ trong callback; preload
-trigger chỉ `Ads.dispatchEvent` khi cờ bật (event màn đầu nhận trong lúc chờ CMP được giữ lại, phát
-sau callback); `setUpAppOpen` bỏ qua khi cờ tắt. Xem wrapper-template.
-
-Ba mối observability — **bắt buộc trước khi verify**, không phải tuỳ chọn:
-
-**(a) Logger sink** — `Ads.logger.init(LogConfig(enabled = true, minLevel = LogLevel.FLOW),
-debug = isDebug, externalSink)` (`LogLevel` không có `VERBOSE`; `FLOW` là mức thấp nhất,
-`SA/domain/model/log/LogLevel.kt:6`). Logcat chỉ ở debug; `ERROR` / `ERROR_AND_CRASH` thì debug Toast (post lên
-main — sink chạy đồng bộ trên luồng đang log, thường là IO; Toast ngoài main thread ném exception và
-bị SDK nuốt trong `runCatching`, `SA/infra/logger/SdkAdLogger.kt:50`, nên Toast không hiện), release
-`Firebase.crashlytics.recordException(Exception(event.toJsonString()))`. Đây là đường duy nhất
-thấy issue `ConfigRegistryCheck`.
-
-**(b) Tracker collector** — collect `Ads.tracker.events` một lần trên `Dispatchers.Main`:
-
-| Event | Việc làm |
-|---|---|
-| `TrackingEvent` | forward `event.eventName` sang Firebase; thêm hậu tố `_oke` / `_fail` theo `FirebaseRemoteConfig.getValue(key).source == VALUE_SOURCE_REMOTE` |
-| `StartRequest` / `Impression` | event bespoke theo `event.data.adItemId` (`logOnce` cho impression) |
-| `UpdateJson` | DEBUG: Toast `"Load version ${event.version}"` |
-| `Click` | DEBUG: Toast `unitId.takeLast(4)` + `adItemId` |
-| `FailedToLoad` / `FailedToShowFull` | DEBUG: Toast kèm `error.code` |
-
-`global.tracking.item_events` mặc định bật (không khai = `true`, từ 3.0.6) ⇒ `SuperAdsTracking` tự forward `TrackingEvent` (kèm `ab_variant`): **bỏ** dòng forward `TrackingEvent` ở trên (hoặc khai `false`), nếu không event bị gửi đôi. Dự án chạy Firebase A/B bằng RC: nạp lại config bằng `Ads.loadFromJson(json, firebaseActivated = true)` **chỉ** sau `activate()` (`loadFromJson(json)` và config provider không push activation event) — xem `MIGRATION.md`, mục A/B test bằng remote config.
-
-**(c) Config provider** — overload `Ads.init(application, configProvider = { ... }, isDebug)`:
-
-```text
-assets = readAssetString(file, timeout 2000)
-remote = getRemoteConfigString(key, fallbackToOldValue = true, timeout 3500)
-remote hợp lệ (parse được JSON object có "placements") ? remote : assets
-```
-
-JSON RC hỏng mà vẫn trả về ⇒ SDK parse ra `null` ⇒ init **FAILED**, mất sạch ad, không có bản dự
-phòng (`SA/runtime/SdkRuntime.kt:226`, `SA/runtime/SdkRuntime.kt:275`). Vì vậy provider phải kiểm
-JSON trước khi trả. Muốn có bản dự phòng: `Ads.init(application, fileNameAsset)` chạy asset ngay, rồi nạp
-giá trị RC sau `fetchAndActivate()` bằng `Ads.loadFromJson(json, firebaseActivated = true)` (`SA/api/Ads.kt:197`);
-JSON hỏng bị từ chối, giữ bản đang chạy — hỏi nhóm C. (`initRemote` mới mở lại, chỉ app mẫu dùng; chưa kiểm trên thiết bị.)
-
-`minimumFetchIntervalInSeconds = 0` như SlideShow là rất hung — hỏi nhóm D. RC key phụ
-`keyTimeBetweenAdInter` không có tương đương.
-
-Cấm thêm vào wrapper: state timing, cache riêng, retry, adapter callback SDK, preload thủ công,
-driver reload, tách file helper theo loại ad.
-
-### Verify Phase 4
-
-- [ ] Chữ ký public của wrapper cũ không đổi
-- [ ] EventScreen emit chuỗi khớp `preload.eventActive` đã viết ở Phase 3b
-- [ ] Ba mối observability đã nối
-- [ ] Không event preload / app open nào chạy trước callback `showCmp`
-- [ ] Checkpoint `migration/04-wrapper`
-
----
-
-## Phase 5 — Call sites, chia hai nhóm
-
-### 5a — Không sửa màn hình
-
-Mọi lời gọi mà wrapper giữ được chữ ký thì **màn hình không đổi một ký tự**:
-`showAdsNative(...)`, `showAdsInterGeneral(...)`, `showNativeCollapsible(...)`,
-`showInterAdsSplash(...)`, `showInterSplashLate(...)`.
-
-### 5b — Danh sách đóng: chỉ những lý do này mới được sửa màn hình
-
-| Lý do | Hành động |
-|---|---|
-| `AdmobX.load(space)` gọi trực tiếp trong màn | Xoá call site (đã ở `preload.eventActive`) |
-| `getStatusBySpace(...) == LOADED` làm gate trước show | Xoá gate (đã ở `mode.show: SHOW_LOADED`) |
-| Gọi lại `showAdsNative("X_Reload", ...)` trong `onAdClicked` | Xoá (đã ở `reload.click.placementID`) |
-| Timer reload trong Fragment | Xoá (đã ở `reload.auto.placementID` + `show.timeAutoReloadMs`) |
-| `AdmobOpenResume.loadAndAutoShowIfAvailable(...)` rải rác | Xoá, dồn về `setUpAppOpen(...)` một lần trong init |
-| Dialog native-sau-inter tự viết | Xoá, dùng `INTERSTITIAL_NATIVE_CHAIN` + `chain.native.showEvery` |
-| Pseudo-reward bằng native dialog | Đổi sang placement `REWARD` / `NATIVE_FULL_ACTIVITY` thật |
-| Màn gọi trực tiếp `Admob*` không qua wrapper | Đổi sang chữ ký wrapper |
-| Base fragment | Thêm hook `EventScreen` |
-| Override `onAdPaidValueListener` / `logPairValue*` trong màn hoặc dialog | Xoá, gom về tracker collector (tên event ở `tracking.event*`) |
-
-Không có lý do trong bảng này thì **không sửa file đó**.
-
-### Verify Phase 5
-
-- [ ] `rg "com.android.fullhd.adssdk"` rỗng
-- [ ] Không còn `.load(` trên code ads
-- [ ] Không còn lời gọi tay tới placement `*_Reload`
-- [ ] Mọi file màn hình bị sửa truy được về đúng một dòng bảng 5b
-- [ ] Ba bảng inventory `status = DONE`
-- [ ] Checkpoint `migration/05-call-sites`
-
----
-
-## Phase 6 — Layout
-
-Layout AdMob chuẩn giữ nguyên. Sửa tay:
-
-- Id badge `ivAdMark` (AdsPro) → `tvAdMark` (SuperAds `ProtectedAssets`).
-- `iv_blur` chỉ còn ý nghĩa với AdMob.
-
-Xoá `R.layout.*` khỏi **thân wrapper** (call site vẫn truyền vào — tham số inert). Đối chiếu
-ngược: mỗi giá trị `ui.layoutAdName*` có file XML tồn tại thật (app res hoặc SuperAdsLayout).
-
-View id bắt buộc: `ad_media`, `ad_app_icon`, `ad_headline`, `ad_body`, `ad_call_to_action`,
-`ad_choices_container`, `tvAdMark`. Optional: `ad_price`, `ad_store`, `ad_stars`, `ad_advertiser`.
-
-### Verify Phase 6
-
-- [ ] Không layout collapsible nào đảo collapsed / expanded
-- [ ] Mọi `ui.layoutAdName*` resolve được
-- [ ] Checkpoint `migration/06-layout`
-
----
-
-## Phase 7 — Cleanup
-
-Xoá dialog ads tự viết và timer đã bị JSON thay thế. Xoá import chết.
-
-**Không** xoá file wrapper. **Không** dọn tham số inert (commit riêng).
-
-Cách SlideShow comment lại 650 dòng `AdsUtils.kt` là điều **không** nên copy — hoặc moi ruột,
-hoặc xoá, không để code chết.
-
-### Verify Phase 7
-
-- [ ] Không còn dialog ads tự viết đã bị `INTERSTITIAL_NATIVE_CHAIN` thay
-- [ ] Không còn file utils ads mới ngoài quyết định nhóm C
-- [ ] Checkpoint `migration/07-cleanup`
-
----
-
-## Global Invariant Check
-
-Chạy sau Phase 7, **trước** build. Đọc [references/verification.md](references/verification.md).
-
-```text
-COUNT(unique AdsPro spaceName) <= COUNT(SuperAds placements)
-AdsPro spaceName  \  SuperAds placements = rỗng
-SuperAds placements \ AdsPro spaceName  ⊆ Bảng D reload extras ∪ Documented exclusions
-COUNT(AdsPro ids toàn bộ) == COUNT(SuperAds units toàn bộ)
-  (gộp unit trùng network+id chỉ khi product yêu cầu; DUPLICATE_UNIT_ID = warning)
-
-COUNT(call site load() cũ) == COUNT(hàng Bảng B đã map)
-mọi chuỗi preload.eventActive ⊆ tập EventScreen app này thực sự emit
-
-mọi adItem NATIVE_COLLAPSIBLE có đủ 2 key layout, và collapsed != expanded
-mọi ui.layoutAdName* trỏ tới file XML tồn tại
-mọi network trong adItem.units có key layout tương ứng
-
-mọi reload.*.placementID trỏ tới placement tồn tại
-mọi placement có show.timeAutoReloadMs đều có reload.auto.placementID
-không placement chain nào mang reload.auto hoặc reload.dismiss
-mọi space reload AdsPro **có call site** là đích của đúng một reload.*.placementID
-zero-call-site reload → Documented exclusions
-nếu Bảng D: layout đích == layout show; unit == unit AdsPro lúc click
-không gộp ≥2 layout nguồn khác nhau vào một adItem reload
-
-file Ads.init / configProvider == file JSON đang migrate
-nếu có chain: len(native) + firstShowAt/showEvery khớp đo app này
-mọi INTER fullscreen: mode.navigate từ callback app, không default SDK
-
-mọi file màn hình bị sửa có lý do thuộc bảng 5b
-mọi tham số inert đã ghi vào bảng Inert parameters
-không có file utils ads mới nào được tạo ngoài quyết định nhóm C
-
-ba mối observability đã nối: logger sink, tracker collector, config provider
-không dispatchEvent / app open nào trước callback consent
-mọi tên event analytics cũ đều có nhà mới (tracking.event* trong JSON, hoặc collector app-side)
-không tên event analytics nào bị mất mà không ghi vào Decisions
-```
-
-Ngoại lệ chỉ hợp lệ khi ghi vào "Documented exclusions".
-
-Sau invariant: build → Toast `UpdateJson` version (bước đầu tiên) → `ConfigRegistryCheck` sạch →
-fill từng placement → semantic matrix → 13 chuỗi `adType` analytics không đổi.
-
-13 chuỗi khoá bởi `AdProfileMappingTest`: `INTER`, `NATIVE`, `NATIVE_COLLAPSIBLE`,
-`NATIVE_FULL_ACTIVITY`, `APP_OPEN`, `BANNER`, `BANNER320x250`, `BANNER_COLLAPSIBLE_TOP`,
-`BANNER_COLLAPSIBLE_BOTTOM`, `REWARD`, `REWARD_INTER`, `NATIVE_CHAIN`,
-`INTERSTITIAL_NATIVE_CHAIN`. Đổi chuỗi ⇒ dashboard doanh thu trắng, không có gì fail.
-
-## Quick Reference
-
-```kotlin
-// Init
-Ads.init(application, configProvider = { getConfig(...) }, isDebug = isDebug)
-Ads.isPremium = purchased
-// Consent TRƯỚC preload/show/app open (core không tự chặn): Activity đầu
-Ads.gdpr.requestAndShowIfRequired(activity, isDebug, timeoutMs = /* timeout AdsPro của app */) { onConsentDone(); next() }
+| preload theo thời điểm | `AdmobX.load(space)` rải rác | `preload.eventActive` |
+| gate "chỉ show khi đã load" | `getStatusBySpace == LOADED` | `mode.show: SHOW_LOADED` |
+| auto reload chu kỳ | timer trong Fragment | `reload.auto.placementID` + `show.timeAutoReloadMs` |
 
-// Inline (native / banner)
-Ads.show(placementId, activity, AdTarget.AdView(container, lifecycle), callback)
+Gọi `Ads.*` tra nhanh: [snippets/ads-api-quick.md](snippets/ads-api-quick.md).
 
-// Fullscreen / reward
-Ads.show(placementId, activity, callback = NavAdCallback { ... })
-Ads.show(placementId, activity, callback = RewardAdCallback(true) { ... })
+## ✅ Best Practices
 
-// Preload — KHÔNG gọi thủ công. EventScreen + preload.eventActive.
-Ads.dispatchEvent(activity, "create_open_screen_5_fo")
-```
+- Placement name giữ **nguyên văn** `spaceName` cũ, kể cả sai chính tả.
+- Đo behavior từ **app đang migrate** (`showEvery`, số native, countdown, RC key, `mode.navigate`), không
+  copy từ SlideShow / app khác.
+- Mỗi tham số inert ghi vào bảng "Inert parameters" kèm một dòng comment trong thân wrapper.
+- Bump `global.version` mỗi lần sửa JSON để Toast `UpdateJson` chứng minh file đang chạy.
+- Code smell còn thấy sau migration là chưa xong: `Handler` / `delay` quanh ads, `countShowAd`,
+  `Ads.preload*` thủ công, `if (status == LOADED)` trước show, `R.layout.*` trong thân wrapper, timer reload
+  trong Fragment.
 
-## Anti-patterns
+## ❌ Anti-patterns
 
 - Mang nguyên `AdsUtils.kt` 650 dòng sang SuperAds.
 - Tạo `LegacyAdCallbackAdapter`.
@@ -782,6 +153,38 @@ Ads.dispatchEvent(activity, "create_open_screen_5_fo")
 - Comment 650 dòng rồi để chết trong repo.
 - Sửa 40 màn hình trong khi chữ ký wrapper giữ được.
 
+## ⚠️ Common Issues
+
+Lỗi runtime (không preload, layout sai cỡ, zero ads, init FAILED…): xem
+[troubleshooting.md](references/troubleshooting.md) và bẫy SDK trong
+[migration-pitfalls.md](references/migration-pitfalls.md).
+
+## Files created
+
+Trong repo **app** được migrate:
+
+- `migration-inventory.md` (Bảng A/B/C/D + Decisions + Inert parameters + Documented exclusions).
+- File JSON config SuperAds (assets).
+- `EventScreen` — ưu tiên thêm vào file base sẵn có; chỉ tạo file mới nếu package base không có nhà hợp lý
+  (quyết định nhóm C).
+
+Skill này không tạo file helper ads mới ngoài quyết định nhóm C.
+
+## Files modified
+
+- Gradle (Phase 1) và `AndroidManifest.xml` (Phase 2).
+- File wrapper cũ (`AdsUtils.kt` hoặc tương đương) — moi ruột, giữ path và chữ ký.
+- Base fragment (hook `EventScreen`).
+- Màn hình / dialog **chỉ** khi có lý do thuộc bảng 5b.
+- Layout native (id badge `tvAdMark`) theo Phase 6.
+
+## Verification
+
+Chạy Global Invariant Check ([global-invariant-check.md](references/global-invariant-check.md)) trước
+build. Sau đó: build → Toast `UpdateJson` version (bước đầu tiên) → `ConfigRegistryCheck` sạch → fill từng
+placement → semantic matrix → 13 chuỗi `adType` analytics không đổi. Chi tiết:
+[verification.md](references/verification.md). Báo output thật; bước bỏ qua thì ghi là bỏ qua.
+
 ## Checklist
 
 - [ ] `migration-inventory.md` tồn tại với Bảng A/B/C/D + Decisions + Inert + Exclusions
@@ -792,13 +195,35 @@ Ads.dispatchEvent(activity, "create_open_screen_5_fo")
 - [ ] Diff budget: số màn hình bị sửa giải thích được bằng bảng 5b
 - [ ] Báo cáo file đã sửa, tóm tắt, và lỗi / vấn đề còn lại
 
+## 📈 Performance Notes
+
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+
+Skill này chính là quy trình migration AdsPro → SuperAds (các phase ở mục Workflow). Nâng cấp SuperAds
+phiên bản thấp lên `>=4.0.0` không thuộc skill này: dùng [super-ads-upgrade](../super-ads-upgrade/SKILL.md).
+
 ## Output
 
 Báo cáo: file đã sửa, tóm tắt từng phase, Decisions đã hỏi, diff budget (config / wrapper / base /
 màn 5b), kết quả invariant + runtime, và lỗi còn lại.
 
-## References
+## Examples
+
+- Hàng mẫu Bảng A/B/C/D: [templates/migration-inventory.md](templates/migration-inventory.md).
+- Gọi `Ads.*` mẫu: [snippets/ads-api-quick.md](snippets/ads-api-quick.md).
+- Wrapper và config đầy đủ: [wrapper-template.md](references/wrapper-template.md),
+  [config-template.md](references/config-template.md).
+
+## 📚 References
 
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-upgrade](../super-ads-upgrade/SKILL.md)
+- [super-ads-add-placement](../super-ads-add-placement/SKILL.md)
 - [references/migration-pitfalls.md](references/migration-pitfalls.md)
 - [references/api-mapping.md](references/api-mapping.md)
 - [references/config-template.md](references/config-template.md)
@@ -806,7 +231,7 @@ màn 5b), kết quả invariant + runtime, và lỗi còn lại.
 - [references/troubleshooting.md](references/troubleshooting.md)
 - [references/verification.md](references/verification.md)
 
-## Tags
+## 🏷️ Tags
 
 - android
 - kotlin