@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/skills/adspro-to-superads/references/global-invariant-check.md

@@ -0,0 +1,49 @@
+# Global Invariant Check
+
+Chạy sau Phase 7, **trước** build. Đọc [verification.md](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.

package/skills/adspro-to-superads/references/migration-contract.md

@@ -0,0 +1,57 @@
+# Migration Contract và Stop Conditions
+
+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 `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).

package/skills/adspro-to-superads/references/phase-0-inventory.md

@@ -0,0 +1,39 @@
+# Phase 0 — Inventory matrix và checkpoint git
+
+## 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 |
+
+
+## Inventory
+
+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-D, Decisions, Inert parameters, Documented exclusions: dùng [templates/migration-inventory.md](../templates/migration-inventory.md).
+
+## 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](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`

package/skills/adspro-to-superads/references/phase-1-2-gradle-manifest.md

@@ -0,0 +1,85 @@
+# Phase 1-2 — Gradle và Manifest
+
+## 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`

package/skills/adspro-to-superads/references/phase-3-config-migration.md

@@ -0,0 +1,159 @@
+# Phase 3 — Config migration
+
+Đọc [config-template.md](config-template.md),
+[api-mapping.md](api-mapping.md) và
+[migration-pitfalls.md](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ũ.
+
+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 |
+|---|---|---|
+| `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`

package/skills/adspro-to-superads/references/phase-4-wrapper-observability.md

@@ -0,0 +1,70 @@
+# 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 [wrapper-template.md](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`

package/skills/adspro-to-superads/references/phase-5-7-callsites-layout-cleanup.md

@@ -0,0 +1,73 @@
+# Phase 5-7 — Call sites, Layout, Cleanup
+
+# 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`

package/skills/adspro-to-superads/references/principles-and-authority.md

@@ -0,0 +1,73 @@
+# 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
+
+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.
+
+# 1. JSON-first
+
+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
+[config-template.md](config-template.md) §"Key theo tầng" và
+[api-mapping.md](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` |
+
+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ó.
+
+```text
+AdsPro:     40 màn  --space + R.layout + timing-->  AdsUtils (650 dòng)  --> Admob*.load/show
+SuperAds:   40 màn KHÔNG ĐỔI --chữ ký cũ-->  AdsUtils moi ruột  --> Ads.show
+                                              EventScreen --> Ads.dispatchEvent
+                                              JSON (format, layout, mode, preload, reload, chain)
+```