@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/skills/super-ads-release-check/SKILL.md

@@ -1,43 +1,95 @@
 ---
 schema: 1
 name: super-ads-release-check
-description: Use when an app using SuperAds is about to ship a release build — evidence-based checklist (versions, test units, isDebug, logger, debug overlay, consent, config validity) that reports findings without editing build files.
-version: 1.2.0
+description: Use when an app using SuperAds is about to ship a release build, to get an evidence-based report-only checklist
+version: 1.3.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Rà SuperAds trước khi phát hành
 
 Checklist **chỉ báo cáo**. Mỗi mục có lệnh kiểm, tiêu chí đạt và nguồn. Skill không sửa file nào; mọi sửa đổi chờ user duyệt.
 
-Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `DBG/` = `super-ads-debug/src/main/java/com/android/fullhd/super_ads/debug/`. `<app>` là module app, `<config>` là file config sẽ phát hành (asset và/hoặc bản remote).
-
 ## When to use
 - Trước khi build release, tạo bản phát hành, hoặc trước khi đẩy config remote mới lên production.
 
-## When NOT to use
+## 🚫 When NOT to use
 - Đang tìm lỗi một ad cụ thể → `super-ads-debug`.
 - Gắn SDK lần đầu → `super-ads-integrate` (chạy skill này ở cuối).
 
-## Authority order
+## 📋 Prerequisites
+- Định tuyến skill và kiểm version SDK: xem [super-ads-guide](../super-ads-guide/SKILL.md).
+- Skill này nhắm SuperAds `>=4.0.0 <5.0.0`. App dùng SuperAds thấp hơn ⇒ **dừng** và khuyến nghị (không ép) nâng cấp qua [super-ads-upgrade](../super-ads-upgrade/SKILL.md) trước khi tiếp tục.
+- Biết module app, build type release, file config sẽ phát hành (asset và/hoặc remote), danh sách network (thu ở Phase 1).
+- Build được release (keystore, artifact có sẵn); MCP `super-ads` cho `validate_config` (mục 11).
+
+## ⚡ Quick Reference
+
+| Cần | Tài liệu |
+|---|---|
+| Bảng 22 mục kiểm | phần `## Checklist` bên dưới |
+| Checklist Firebase A/B (mục 22) | [references/firebase-ab-checklist.md](references/firebase-ab-checklist.md) |
+| Custom dimension/metric GA4 (mục 20) | [references/ga4-custom-definitions.md](references/ga4-custom-definitions.md) |
+
+Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `DBG/` = `super-ads-debug/src/main/java/com/android/fullhd/super_ads/debug/`. `<app>` là module app, `<config>` là file config sẽ phát hành (asset và/hoặc bản remote).
+
+Kết quả mỗi mục: `PASS` / `FAIL` / `CẦN QUYẾT ĐỊNH` / `SKIP`.
+
+## 🏗️ Recommended Architecture
+Thứ tự thẩm quyền khi các nguồn mâu thuẫn:
 1. Code SDK và Gradle thật của app (output `dependencies`, không phải đọc tay).
 2. `MIGRATION.md`.
 3. Quy ước phát hành của nhóm do user cung cấp. Mục nào là **quyết định sản phẩm** thì báo "cần quyết định", không báo "lỗi".
 
-## Contract
-**MUST**
+## Workflow
+
+### Stop conditions
+- Không build được release (thiếu keystore, thiếu artifact): báo nguyên văn lỗi, không tự sửa.
+- Không lấy được config remote đang dùng: hỏi user nguồn config.
+
+### Phase 1: Thu thông tin
+Module app, build type release, file config (asset và remote), danh sách network.
+
+**Verify:** biết `<app>`, `<config>`, nguồn config remote (hoặc "không dùng").
+
+### Phase 2: Chạy checklist
+Chạy từng mục theo bảng ở `## Checklist`. Mục cần build release (1–3, 13, 15, 16, 18) chạy sau cùng, một lần build.
+
+**Verify:** 22 mục đều có kết quả và bằng chứng.
+
+### Phase 3: Báo cáo
+Bảng `# | mục | kết quả | bằng chứng | đề xuất`. `FAIL` và `CẦN QUYẾT ĐỊNH` đưa lên đầu. Đề xuất sửa nêu file và dòng, nhưng **không** sửa.
+
+**Verify:** không có `PASS` nào thiếu bằng chứng.
+
+## 🔧 API Reference
+> **Not applicable for this skill.**
+
+## ✅ Best Practices
 - Chạy lệnh thật và trích output cho từng mục. Không chạy được thì ghi `SKIP` kèm lý do.
 - Kết quả mỗi mục: `PASS` / `FAIL` / `CẦN QUYẾT ĐỊNH` / `SKIP`.
 - Kiểm cả config asset **và** config remote (nếu app dùng remote).
 
-**MUST NOT**
-- Không sửa Gradle, manifest, `Application`, config.
-- Không đẩy config lên Firebase hay server.
-- Không coi build debug pass là bằng chứng cho build release.
+## ❌ Anti-patterns
+- Sửa Gradle, manifest, `Application`, config.
+- Đẩy config lên Firebase hay server.
+- Coi build debug pass là bằng chứng cho build release.
+- Đọc `build.gradle` bằng mắt thay cho output `dependencies` (version có thể bị BOM hoặc resolution đổi).
+- Chỉ kiểm config asset trong khi production dùng config remote.
+- Báo overlay debug là "lỗi" khi app cố ý giữ nó: đó là quyết định của user.
 
-## Stop conditions
-- Không build được release (thiếu keystore, thiếu artifact): báo nguyên văn lỗi, không tự sửa.
-- Không lấy được config remote đang dùng: hỏi user nguồn config.
+## ⚠️ Common Issues
+> **Not applicable for this skill.**
+
+## Files created
+Skill này không tạo file nguồn.
+
+## Files modified
+Skill này không sửa file nguồn (Gradle, manifest, `Application`, config đều chỉ đọc). Mọi sửa đổi chờ user duyệt.
+
+## Verification
+Mọi mục trong bảng `## Checklist` có kết quả kèm output lệnh thật làm bằng chứng; không có `PASS` nào thiếu bằng chứng; mục không chạy được ghi `SKIP` kèm lý do.
 
 ## Checklist
 
@@ -59,7 +111,7 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `
 | 14 | Plugin đủ cho config | Mỗi `network` trong `units` của config có artifact tương ứng, **và luôn có `SuperAdsInHouse`** dù config không có unit InHouse | Không thiếu plugin (thiếu ⇒ `LOAD:212`; thiếu InHouse ⇒ log `ERROR_AND_CRASH` tag `RequiredPluginCheck` lúc init; `ConfigRegistryCheck` log lúc init "KHÔNG có AdNetworkPlugin nào register" hoặc "no PROVIDER for (…)") | `SA/config/validate/ConfigRegistryCheck.kt:33-35`, `SA/config/validate/ConfigRegistryCheck.kt:88`, `super-ads/src/main/java/com/android/fullhd/super_ads/config/validate/RequiredPluginCheck.kt:27-31` |
 | 15 | R8 / minify | Build `:<app>:assembleRelease`; chạy bản release, xem có `ClassNotFoundException` / `NoSuchMethodError` / `NoClassDefFoundError` liên quan `com.android.fullhd`. App có module phụ (`SuperAdsDebug`, `SuperAdsDebugOverride`, `super-ads-test`) mà bật `minifyEnabled` cả ở debug ⇒ chạy thêm bản debug đó: các module này là AAR riêng gọi thẳng class của core (vd `config.parse.AdsConfigParserV2`), class nào ngoài rule keep của core bị R8 đổi tên/xoá ⇒ `NoClassDefFoundError` lúc init. Phát hành core/plugin mới: `node --test test/r8-cross-module-keep.test.js` trong `tools/ai_agent_tools` phải xanh | `SA/domain/error/AdError.kt:17` |
 | 16 | Tracking Firebase | Cùng lệnh mục 1, grep `SuperAdsTracking`; đọc `global` của `<config>`: `tracking.enable`, `tracking.revenue`, `tracking.perf`, `tracking.arbiter` | App cần doanh thu Firebase ⇒ có `SuperAdsTracking`, và `tracking.enable` / `tracking.revenue` không bị tắt ngoài ý muốn (mặc định `true` / `true`). Thiếu module ⇒ mất `ad_impression` và `ad_click`, không có lỗi. Không rõ app có cần không ⇒ `CẦN QUYẾT ĐỊNH` | `MIGRATION.md:450-452`, `SA/domain/config/model/AdsConfig.kt:81`, `SA/domain/config/model/AdsConfig.kt:85` |
-| 17 | `global.remoteApplyTimeoutMs` | Đọc `global` của config asset (gác mọi lần đổi config: `loadFromJson`, remote, `reload`) | `0` (không giới hạn) hoặc giá trị user đã chọn. Giá trị > 0: config về sau hạn (vd Remote Config chậm) bị bỏ cả phiên, không push activation ⇒ báo `CẦN QUYẾT ĐỊNH` | `SA/domain/config/model/AdsConfig.kt:77`, `SA/config/remote/RemoteConfigLoader.kt:170-173` |
+| 17 | `global.remoteApplyTimeoutMs` | Đọc `global` của config asset (gác mọi lần đổi config: `loadFromJson`, remote, `reload`) | `0` (không giới hạn) hoặc giá trị user đã chọn. Giá trị > 0: config về sau hạn (vd Remote Config chậm) bị bỏ cả phiên, không push activation ⇒ báo `CẦN QUYẾT ĐỊNH` | `SA/domain/config/model/AdsConfig.kt:77`, `SA/config/remote/RemoteConfigLoader.kt:256-259` |
 | 18 | Không đóng gói file tạm của MCP | `find <app>/src -path "*assets*" -name "tmp-*.json"`; liệt kê asset của APK release | Không có `tmp-*.json` do MCP `super-ads` tự sinh, không có `.super-ads-tmp/` trong asset | `tools/ai_agent_tools/README.md:62`, `tools/ai_agent_tools/README.md:66-70` |
 | 19 | Không có module override config ở release | `./gradlew :app:dependencies --configuration releaseRuntimeClasspath` tìm `SuperAdsDebugOverride` / `super-ads-debug-override`; `unzip` dex của APK release, `grep -ac debugoverride` và `grep -ac superads_override`; grep `debugoverride` trong merged manifest release | Tất cả bằng 0 (module phải là `debugImplementation`). Áp dụng khi app khai module (`super-ads-debug-override`); không khai ⇒ `SKIP` | [hook-implementation.md](../super-ads-debug-override/references/hook-implementation.md) |
 | 20 | Custom dimension/metric GA4 đã đăng ký cho tính năng tracking đang bật | Đọc `global` của `<config>` (`tracking.enable`, `revenue`, `perf`, `arbiter`, `spa_ad_revenue`, `item_events`, `activation_event`; asset và remote) + dependency `SuperAdsTracking` (mục 16); tra bảng trong [ga4-custom-definitions.md](references/ga4-custom-definitions.md); đối chiếu với custom definitions của property GA4 (user đọc từ GA4 Admin, hoặc GA4 MCP `ga4_metadata` nếu đã kết nối) | Mọi dimension/metric của tính năng đang bật đã đăng ký đúng **tên**, scope Event, đơn vị (`*_ms` = milliseconds, `revenue_usd` = USD). Thiếu ⇒ `FAIL` kèm danh sách param thiếu. Không xác minh được ⇒ `CẦN QUYẾT ĐỊNH`, không `PASS`. Đăng ký **không backfill**: phải làm trước khi phát hành/bật cờ; đổi cờ ⇒ chạy lại mục này | `MIGRATION.md:472-480`, `super-ads-tracking/src/main/java/com/android/fullhd/super_ads/tracking/collector/TrackingCollector.kt:58-129` |
@@ -68,25 +120,26 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `
 
 Mục 8: bộ nền khai `SuperAdsDebug` bằng `implementation` nên overlay có ở release (app mẫu cũng vậy: `app/build.gradle:102`; comment giải thích nằm lệch ở `app/build.gradle:62-63`, ngay trên dòng `:super-ads-admob`). Việc cần ghi nhận là ai mở được nó: `enableDBView` và lời gọi `Ads.openDBBridge` (app mẫu có nút gọi nó: `app/src/main/java/com/android/hd/ads2026/MainActivity.kt:69`).
 
-## Phase 1: Thu thông tin
-Module app, build type release, file config (asset và remote), danh sách network.
-
-**Verify:** biết `<app>`, `<config>`, nguồn config remote (hoặc "không dùng").
+## 📈 Performance Notes
+> **Not applicable for this skill.**
 
-## Phase 2: Chạy checklist
-Chạy từng mục theo bảng. Mục cần build release (1–3, 13, 15, 16, 18) chạy sau cùng, một lần build.
+## 🔒 Security Notes
+> **Not applicable for this skill.**
 
-**Verify:** 22 mục đều có kết quả và bằng chứng.
+## 🔄 Migration Guide
+> **Not applicable for this skill.**
 
-## Phase 3: Báo cáo
-Bảng `# | mục | kết quả | bằng chứng | đề xuất`. `FAIL` và `CẦN QUYẾT ĐỊNH` đưa lên đầu. Đề xuất sửa nêu file và dòng, nhưng **không** sửa.
+## Output
+Bảng 22 mục kèm bằng chứng, danh sách việc cần sửa (chờ duyệt), các mục `SKIP` kèm lý do.
 
-**Verify:** không có `PASS` nào thiếu bằng chứng.
+## Examples
+- [references/firebase-ab-checklist.md](references/firebase-ab-checklist.md): checklist chạy cho mục 22.
+- [references/ga4-custom-definitions.md](references/ga4-custom-definitions.md): bảng dimension/metric cho mục 20.
 
-## Anti-patterns
-- Đọc `build.gradle` bằng mắt thay cho output `dependencies` (version có thể bị BOM hoặc resolution đổi).
-- Chỉ kiểm config asset trong khi production dùng config remote.
-- Báo overlay debug là "lỗi" khi app cố ý giữ nó: đó là quyết định của user.
+## 📚 References
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-upgrade](../super-ads-upgrade/SKILL.md)
+- [super-ads-integrate](../super-ads-integrate/SKILL.md), [super-ads-debug](../super-ads-debug/SKILL.md), [super-ads-debug-override](../super-ads-debug-override/SKILL.md), [super-ads-ab-test](../super-ads-ab-test/SKILL.md)
+- `MIGRATION.md`
 
-## Output
-Bảng 22 mục kèm bằng chứng, danh sách việc cần sửa (chờ duyệt), các mục `SKIP` kèm lý do.
+## 🏷️ Tags
+`super-ads` `release` `checklist` `report-only` `r8` `consent` `ga4`

package/skills/super-ads-show-rate/SKILL.md

@@ -1,53 +1,51 @@
 ---
 schema: 1
 name: super-ads-show-rate
-description: Use when you need to measure or explain the show rate of SuperAds placements (shown / show requests), find why show attempts end blocked or failed, and propose evidence-backed config changes.
-version: 1.0.0
+description: Use when measuring or explaining SuperAds placement show rate (shown / requested) and why shows are blocked or fail
+version: 1.1.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Show rate của SuperAds
 
 Đo **show rate = số lần show có Impression / số lần gọi `Ads.show`** theo placement, tách phần bị chặn (blocked) khỏi phần lỗi (error), rồi giải thích bằng mã lỗi và tri thức key.
 
-| Bước | Tài liệu |
-|---|---|
-| Định nghĩa, nguồn đo, giới hạn | [references/metrics.md](references/metrics.md) |
-| Thu số liệu bằng Logcat | [references/collect-snippet.md](references/collect-snippet.md) |
-| Bật log SDK | [../super-ads-debug/references/logging-setup.md](../super-ads-debug/references/logging-setup.md) |
-| Mã lỗi | [../super-ads-debug/references/error-codes.md](../super-ads-debug/references/error-codes.md) |
-
-Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `DBG/` = `super-ads-debug/src/main/java/com/android/fullhd/super_ads/debug/`.
-
 ## When to use
 - "Placement X show được bao nhiêu phần trăm?", "vì sao inter ít hiện?", so sánh trước/sau khi đổi config, đánh giá A/B.
 
-## When NOT to use
-- Một lần show hỏng cụ thể cần tìm nguyên nhân → `super-ads-debug`.
+## 🚫 When NOT to use
+- Một lần show hỏng cụ thể cần tìm nguyên nhân → [super-ads-debug](../super-ads-debug/SKILL.md).
 - Fill rate hoặc doanh thu theo network: show rate không đo những thứ này (xem [metrics.md](references/metrics.md) mục 1).
 
-## Contract
-**MUST**
-- Dùng đúng định nghĩa của SDK: kết quả của request là event kết thúc **đầu tiên** (`DBG/model/PlacementShowStats.kt:10-29`).
-- Báo `requested`, `shown`, `blocked`, `error`, `pending` cùng với tỷ lệ. Không báo mỗi phần trăm.
-- Tách blocked với error theo `FailCategory.isBlocked` (`SA/api/debug/AdShowEvent.kt:97-127`). Liệt kê lý do theo `CATEGORY:code`.
-- Ghi rõ nguồn đo và độ tin cậy:
-  - `showEvents` có `seq` nhảy cóc nghĩa là mất event, số liệu chỉ là best-effort;
-  - Firebase luôn là xấp xỉ: bỏ sót blocked, và đếm dư impression sau reload ([metrics.md](references/metrics.md) mục 2).
-- Đề xuất đổi key phải dẫn ý nghĩa từ `tools/ai_agent_tools/data/ads_key_knowledge.json`. Không có nguồn SDK thì ghi "khuyến nghị cần xác nhận".
+## 📋 Prerequisites
+- Routing 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`. App dùng SuperAds thấp hơn thì **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.
+- Một nguồn đo: app có `super-ads-debug` (overlay hoặc `Ads.debug.showEvents`), hoặc Firebase `spa_*` (module `super-ads-tracking` và config bật `global.tracking.perf` cùng `global.tracking.enable`), hoặc file `.logads`. Không có nguồn nào thì không đo được show rate theo request (xem "Dừng và hỏi user khi").
+- Một kịch bản đo đã chốt (placement nào, số lần show, thứ tự màn hình).
+- Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `DBG/` = `super-ads-debug/src/main/java/com/android/fullhd/super_ads/debug/`.
 
-**MUST NOT**
-- Không tính show rate từ `Ads.debug.snapshot()`: snapshot không có số request (`SA/api/debug/AdsDebugSnapshot.kt:19-54`).
-- Không gộp show rate với fill rate.
-- Không kết luận từ dưới 3 request đã có kết quả. Overlay cũng không cảnh báo dưới ngưỡng này (`DBG/data/AdDebugModelBuilder.kt:70-71`).
-- Không tự đổi tần suất ad (`show.timeBetweenMs`, `show.maxShow`…) khi user chưa đồng ý.
+## ⚡ Quick Reference
+| Cần | Mở |
+|---|---|
+| Định nghĩa, nguồn đo, giới hạn, lý do blocked/error | [references/metrics.md](references/metrics.md) |
+| Cách thu số liệu bằng Logcat | [references/collect-snippet.md](references/collect-snippet.md) |
+| Đoạn Kotlin in mỗi `AdShowEvent` một dòng (cần user đồng ý) | [snippets/show-events-logger.md](snippets/show-events-logger.md) |
+| Tính show rate từ log đã thu | [scripts/show-rate.sh](scripts/show-rate.sh) |
+| Bật log SDK | [../super-ads-debug/references/logging-setup.md](../super-ads-debug/references/logging-setup.md) |
+| Mã lỗi | [../super-ads-debug/references/error-codes.md](../super-ads-debug/references/error-codes.md) |
 
-## Stop conditions
+## 🏗️ Recommended Architecture
+> **Not applicable for this skill.**
+
+## Workflow
+
+### Dừng và hỏi user khi
 - App không có `super-ads-debug` và user không đồng ý thêm, cũng không có Firebase `spa_*`: không đo được show rate theo request. Báo rõ và đề xuất lựa chọn.
 - Kịch bản đo chưa được chốt (bao nhiêu lần show, thứ tự màn hình): hỏi user.
 - Kết quả gợi ý đổi chính sách kiếm tiền (giảm cooldown, tăng `maxShow`): trình bày đánh đổi, chờ user quyết.
 
-## Phase 1: Chọn nguồn đo
+### Phase 1: Chọn nguồn đo
 1. App có `super-ads-debug` (artifact `SuperAdsDebug` / module `:super-ads-debug`)?
    - Có, và có máy test: đọc overlay (tab Ads Debugger), hoặc thêm đoạn thu ở [collect-snippet.md](references/collect-snippet.md) (hỏi user trước khi sửa code).
    - Không: Firebase `spa_*` nếu đã cài module `super-ads-tracking` và config bật `global.tracking.perf` (cùng `global.tracking.enable`). Ghi là xấp xỉ.
@@ -55,38 +53,91 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `
 
 **Verify:** có nguồn đo và kịch bản đã chốt.
 
-## Phase 2: Thu số liệu
+### Phase 2: Thu số liệu
 - Overlay: ghi badge `rate · shown/requested` và các lý do chặn/lỗi của từng placement. Ghi cả cảnh báo mất event nếu có.
-- Logcat: `adb logcat -v raw -s SuperAdsShowRate:I > showrate.log` trong lúc chạy kịch bản. Muốn chạy lặp lại tự động thì dùng `super-ads-adb-test`. Log SDK (lý do chặn/lỗi) nằm trong file `.logads` ([logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 6); tag `SuperAdsShowRate` thì không.
+- Logcat: `adb logcat -v raw -s SuperAdsShowRate:I > showrate.log` trong lúc chạy kịch bản. Muốn chạy lặp lại tự động thì dùng [super-ads-adb-test](../super-ads-adb-test/SKILL.md). Log SDK (lý do chặn/lỗi) nằm trong file `.logads` ([logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 6); tag `SuperAdsShowRate` thì không.
 
 **Verify:** mỗi placement trong kịch bản có `requested > 0`.
 
-## Phase 3: Tính và phân loại
-- Chạy script awk ở [collect-snippet.md](references/collect-snippet.md) mục 3, hoặc đọc overlay.
+### Phase 3: Tính và phân loại
+- Chạy [scripts/show-rate.sh](scripts/show-rate.sh) `showrate.log` (awk, ở [collect-snippet.md](references/collect-snippet.md) mục 3), hoặc đọc overlay.
 - Lập bảng: `placement | requested | shown | blocked | error | pending | rate | top lý do (CATEGORY:code × số lần)`.
 - `LOAD:204` là lỗi gộp: tách lỗi con từ `msg=` (đoạn thu ở [collect-snippet.md](references/collect-snippet.md)) hoặc log `PrioChaiLo` / `ProviderTracker` trước khi giải thích ([metrics.md](references/metrics.md) mục 3).
 
 **Verify:** `shown + blocked + error + pending = requested` cho mỗi placement.
 
-## Phase 4: Giải thích và đề xuất
+### Phase 4: Giải thích và đề xuất
 - Tra lý do trong [metrics.md](references/metrics.md) mục 3, và trong [error-codes.md](../super-ads-debug/references/error-codes.md).
 - Blocked đúng thiết kế (cooldown 101, premium 103, guard 108): nêu là chủ đích của config, kèm key và giá trị đang đặt (đọc config bằng MCP `read_working_config`).
-- Error (no-fill, timeout, render): chuyển sang `super-ads-debug` để tìm nguyên nhân gốc.
+- Error (no-fill, timeout, render): chuyển sang [super-ads-debug](../super-ads-debug/SKILL.md) để tìm nguyên nhân gốc.
 - Mỗi đề xuất ghi rõ: key, giá trị trước/sau, hành vi dự kiến (theo tri thức key, kèm `confidence`), rủi ro, cách đo lại.
 
 **Verify:** mỗi đề xuất có nguồn (tri thức key hoặc mã lỗi), hoặc mang nhãn "khuyến nghị cần xác nhận".
 
-## Anti-patterns
+## 🔧 API Reference
+Nguồn đo và định nghĩa: [metrics.md](references/metrics.md). Sự kiện `Ads.debug.showEvents` và đoạn thu: [collect-snippet.md](references/collect-snippet.md).
+
+## ✅ Best Practices
+- Dùng đúng định nghĩa của SDK: kết quả của request là event kết thúc **đầu tiên** (`DBG/model/PlacementShowStats.kt:10-29`).
+- Báo `requested`, `shown`, `blocked`, `error`, `pending` cùng với tỷ lệ. Không báo mỗi phần trăm.
+- Tách blocked với error theo `FailCategory.isBlocked` (`SA/api/debug/AdShowEvent.kt:97-127`). Liệt kê lý do theo `CATEGORY:code`.
+- Ghi rõ nguồn đo và độ tin cậy:
+  - `showEvents` có `seq` nhảy cóc nghĩa là mất event, số liệu chỉ là best-effort;
+  - Firebase luôn là xấp xỉ: bỏ sót blocked, và đếm dư impression sau reload ([metrics.md](references/metrics.md) mục 2).
+- Đề xuất đổi key phải dẫn ý nghĩa từ `tools/ai_agent_tools/data/ads_key_knowledge.json`. Không có nguồn SDK thì ghi "khuyến nghị cần xác nhận".
+
+## ❌ Anti-patterns
+- Tính show rate từ `Ads.debug.snapshot()`: snapshot không có số request (`SA/api/debug/AdsDebugSnapshot.kt:19-54`).
+- Gộp show rate với fill rate.
+- Kết luận từ dưới 3 request đã có kết quả. Overlay cũng không cảnh báo dưới ngưỡng này (`DBG/data/AdDebugModelBuilder.kt:70-71`).
+- Tự đổi tần suất ad (`show.timeBetweenMs`, `show.maxShow`…) khi user chưa đồng ý.
 - Lấy `showCount` trong snapshot chia cho số lần bấm nút.
 - So show rate giữa hai lần đo có kịch bản khác nhau.
 - Coi `LOAD:211` (maxShow) là lỗi network. Nó là giới hạn do config đặt ra.
 - Báo cáo show rate từ Firebase mà không ghi chú phần blocked bị bỏ sót.
 
+## ⚠️ Common Issues
+**`seq` của `showEvents` nhảy cóc.**
+Cause: mất event. Solution: vẫn báo số liệu nhưng ghi rõ chỉ là best-effort (script cũng in cảnh báo).
+
+**`LOAD:204` chiếm phần lớn lỗi nhưng không rõ nguyên nhân.**
+Cause: đây là lỗi gộp, lỗi load từng adItem bị gói vào đó. Solution: tách lỗi con từ `msg=` hoặc log `PrioChaiLo` / `ProviderTracker` ([metrics.md](references/metrics.md) mục 3).
+
+## Files created
+Mặc định skill này không tạo file nào trong app; nó chỉ ghi file số liệu về máy phân tích (`showrate.log`). Khi user đồng ý thêm đoạn thu (Phase 1) mới có file hoặc đoạn code mới trong app.
+
+## Files modified
+Mặc định skill này không sửa file nào của app. Chỉ khi user đồng ý, `Application` được thêm đoạn Kotlin trong [snippets/show-events-logger.md](snippets/show-events-logger.md) (chỉ `BuildConfig.DEBUG`); tần suất ad (`show.timeBetweenMs`, `show.maxShow`…) không bao giờ đổi khi chưa được user duyệt.
+
+## Verification
+Mỗi phase có dòng **Verify** riêng ở Workflow. Kết thúc: `shown + blocked + error + pending = requested` cho mỗi placement, và mỗi đề xuất có nguồn hoặc nhãn cần xác nhận.
+
 ## Checklist
 - [ ] Nguồn đo và độ tin cậy được ghi rõ.
 - [ ] Bảng số liệu cộng đúng `requested`.
 - [ ] Lý do theo `CATEGORY:code`, đã tách blocked/error.
 - [ ] Đề xuất có nguồn, hoặc mang nhãn cần xác nhận.
 
+## 📈 Performance Notes
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+> **Not applicable for this skill.**
+
 ## Output
 Bảng số liệu theo placement, cảnh báo độ tin cậy (mất event / nguồn xấp xỉ), giải thích các lý do hàng đầu, đề xuất (nếu có) kèm cách đo lại.
+
+## Examples
+Bảng kết quả mẫu (một dòng mỗi placement, đúng định dạng của [scripts/show-rate.sh](scripts/show-rate.sh)): `inter  req=3 shown=1 blocked=1 error=1 pending=0 rate=33%`. Cách thu log đầu vào: [references/collect-snippet.md](references/collect-snippet.md).
+
+## 📚 References
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-upgrade](../super-ads-upgrade/SKILL.md)
+- [super-ads-debug](../super-ads-debug/SKILL.md), [super-ads-adb-test](../super-ads-adb-test/SKILL.md)
+- [Bật log SDK](../super-ads-debug/references/logging-setup.md), [Mã lỗi](../super-ads-debug/references/error-codes.md)
+- `MIGRATION.md`, `tools/ai_agent_tools/data/ads_key_knowledge.json`
+
+## 🏷️ Tags
+`superads` `show-rate` `metrics` `blocked` `fill-rate` `showevents`

package/skills/super-ads-show-rate/references/collect-snippet.md

@@ -7,28 +7,7 @@ Chỉ thêm đoạn này khi user đã đồng ý sửa code app. Nếu app đã
 
 ## 1. Kotlin: in mỗi event một dòng
 
-```kotlin
-// Application.onCreate (chỉ BuildConfig.DEBUG), sau Ads.logger.init, trước/sau Ads.init đều được.
-if (BuildConfig.DEBUG) {
-    CoroutineScope(SupervisorJob() + Dispatchers.Default).launch {
-        Ads.debug.showEvents.collect { e ->
-            val (type, extra) = when (e) {
-                is AdShowEvent.Requested -> "REQ" to ""
-                is AdShowEvent.Impression -> "IMP" to ""
-                is AdShowEvent.Failed -> "FAIL" to " cat=${e.category.name} blocked=${e.category.isBlocked} code=${e.code} msg=${e.message}"
-                is AdShowEvent.Clicked -> "CLICK" to ""
-                is AdShowEvent.Dismissed -> "DISMISS" to ""
-                else -> "OTHER" to ""
-            }
-            Log.i("SuperAdsShowRate", "seq=${e.seq} req=${e.requestId} pl=${e.placementId} type=$type$extra")
-        }
-    }
-}
-```
-
-Import: `android.util.Log`, `com.android.fullhd.super_ads.api.Ads`, `com.android.fullhd.super_ads.api.debug.AdShowEvent`, `kotlinx.coroutines.CoroutineScope`, `kotlinx.coroutines.Dispatchers`, `kotlinx.coroutines.SupervisorJob`, `kotlinx.coroutines.launch`.
-
-`msg=` luôn đứng cuối dòng: với `LOAD:204` (`AllPriorityExhausted`) nó chứa các lỗi con, vì lỗi load của từng adItem không tới app trực tiếp ([error-codes.md](../../super-ads-debug/references/error-codes.md), mục "Cách đọc").
+Đoạn mã, danh sách import và lưu ý về `msg=` nằm ở [../snippets/show-events-logger.md](../snippets/show-events-logger.md).
 
 ## 2. Thu log
 
@@ -39,20 +18,7 @@ adb logcat -v raw -s SuperAdsShowRate:I > showrate.log
 
 ## 3. Tính theo placement (kết quả = event kết thúc đầu tiên của mỗi `req`)
 
-```bash
-awk '
-{ delete f; for (i = 1; i <= NF; i++) { if ($i ~ /^msg=/) break; split($i, kv, "="); f[kv[1]] = kv[2] } }
-f["type"] == "REQ" { pl[f["req"]] = f["pl"]; reqs[f["pl"]]++; if (last && f["seq"] != last + 1) gap += f["seq"] - last - 1; last = f["seq"]; next }
-{ if (last && f["seq"] != last + 1) gap += f["seq"] - last - 1; last = f["seq"] }
-(f["type"] == "IMP" || f["type"] == "FAIL") && !(f["req"] in done) && (f["req"] in pl) {
-  done[f["req"]] = 1; p = pl[f["req"]]
-  if (f["type"] == "IMP") shown[p]++; else { if (f["blocked"] == "true") blk[p]++; else err[p]++ }
-}
-END {
-  for (p in reqs) printf "%-40s req=%d shown=%d blocked=%d error=%d pending=%d rate=%.0f%%\n", p, reqs[p], shown[p], blk[p], err[p], reqs[p] - shown[p] - blk[p] - err[p], 100 * shown[p] / reqs[p]
-  if (gap) printf "CẢNH BÁO: mất %d event (seq nhảy cóc), số liệu chỉ là best-effort\n", gap
-}' showrate.log
-```
+Chạy [../scripts/show-rate.sh](../scripts/show-rate.sh) `showrate.log` (awk: mỗi `req` tính theo event kết thúc đầu tiên; cảnh báo khi `seq` nhảy cóc).
 
 Danh sách lý do theo placement: `grep "type=FAIL" showrate.log | sed -E 's/.*pl=([^ ]+) .*cat=([^ ]+) .*code=([0-9]+) msg=.*/\1 \2:\3/' | sort | uniq -c | sort -rn`.
 

package/skills/super-ads-show-rate/scripts/show-rate.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Tính show rate theo placement từ log `SuperAdsShowRate` (snippets/show-events-logger.md).
+# Kết quả của mỗi `req` là event kết thúc ĐẦU TIÊN (Impression hoặc Failed).
+#
+# Thu log:   adb logcat -c && adb logcat -v raw -s SuperAdsShowRate:I > showrate.log
+# Cách dùng: show-rate.sh showrate.log
+set -euo pipefail
+
+if [ "$#" -ne 1 ] || [ ! -f "$1" ]; then
+  sed -n '2,6p' "$0" | sed 's/^# \{0,1\}//' >&2
+  exit 2
+fi
+
+awk '
+{ delete f; for (i = 1; i <= NF; i++) { if ($i ~ /^msg=/) break; split($i, kv, "="); f[kv[1]] = kv[2] } }
+f["type"] == "REQ" { pl[f["req"]] = f["pl"]; reqs[f["pl"]]++; if (last && f["seq"] != last + 1) gap += f["seq"] - last - 1; last = f["seq"]; next }
+{ if (last && f["seq"] != last + 1) gap += f["seq"] - last - 1; last = f["seq"] }
+(f["type"] == "IMP" || f["type"] == "FAIL") && !(f["req"] in done) && (f["req"] in pl) {
+  done[f["req"]] = 1; p = pl[f["req"]]
+  if (f["type"] == "IMP") shown[p]++; else { if (f["blocked"] == "true") blk[p]++; else err[p]++ }
+}
+END {
+  for (p in reqs) printf "%-40s req=%d shown=%d blocked=%d error=%d pending=%d rate=%.0f%%\n", p, reqs[p], shown[p], blk[p], err[p], reqs[p] - shown[p] - blk[p] - err[p], 100 * shown[p] / reqs[p]
+  if (gap) printf "CẢNH BÁO: mất %d event (seq nhảy cóc), số liệu chỉ là best-effort\n", gap
+}' "$1"

package/skills/super-ads-show-rate/snippets/show-events-logger.md

@@ -0,0 +1,26 @@
+# Đoạn Kotlin: in mỗi `AdShowEvent` một dòng
+
+> Chỉ dùng ở bản debug/QA, và chỉ thêm khi user đã đồng ý sửa code app. Cách dùng và cách tính: [../references/collect-snippet.md](../references/collect-snippet.md).
+
+```kotlin
+// Application.onCreate (chỉ BuildConfig.DEBUG), sau Ads.logger.init, trước/sau Ads.init đều được.
+if (BuildConfig.DEBUG) {
+    CoroutineScope(SupervisorJob() + Dispatchers.Default).launch {
+        Ads.debug.showEvents.collect { e ->
+            val (type, extra) = when (e) {
+                is AdShowEvent.Requested -> "REQ" to ""
+                is AdShowEvent.Impression -> "IMP" to ""
+                is AdShowEvent.Failed -> "FAIL" to " cat=${e.category.name} blocked=${e.category.isBlocked} code=${e.code} msg=${e.message}"
+                is AdShowEvent.Clicked -> "CLICK" to ""
+                is AdShowEvent.Dismissed -> "DISMISS" to ""
+                else -> "OTHER" to ""
+            }
+            Log.i("SuperAdsShowRate", "seq=${e.seq} req=${e.requestId} pl=${e.placementId} type=$type$extra")
+        }
+    }
+}
+```
+
+Import: `android.util.Log`, `com.android.fullhd.super_ads.api.Ads`, `com.android.fullhd.super_ads.api.debug.AdShowEvent`, `kotlinx.coroutines.CoroutineScope`, `kotlinx.coroutines.Dispatchers`, `kotlinx.coroutines.SupervisorJob`, `kotlinx.coroutines.launch`.
+
+`msg=` luôn đứng cuối dòng: với `LOAD:204` (`AllPriorityExhausted`) nó chứa các lỗi con, vì lỗi load của từng adItem không tới app trực tiếp ([error-codes.md](../../super-ads-debug/references/error-codes.md), mục "Cách đọc").

package/skills/super-ads-upgrade/SKILL.md

@@ -0,0 +1,137 @@
+---
+schema: 1
+name: super-ads-upgrade
+description: Use when an app uses an older SuperAds SDK than a skill needs, or the user asks to upgrade SuperAds
+version: 1.0.0
+group: Ads
+superAds: ">=4.0.0 <5.0.0"
+---
+
+# Nâng cấp SuperAds
+
+Đưa app từ bản SuperAds cũ lên bản mới nhất theo từng bước nhảy trong `MIGRATION.md`: lên kế hoạch, được user duyệt, nâng core và mọi plugin cùng bản, đổi import, logic và key config, kiểm, rồi bàn giao changelog.
+
+## When to use
+- `super-ads-guide` phát hiện version SuperAds của app thấp hơn khoảng `superAds` của skill, và user đồng ý nâng.
+- User yêu cầu nâng SuperAds (vd "nâng SuperAds lên 4.0.0", "update SDK ads").
+- Core và plugin trong app lệch version, cần đưa về cùng một bản.
+- Build lỗi `NoClassDefFoundError` / `NoSuchMethodError` sau khi nâng một phần.
+
+## 🚫 When NOT to use
+- App chưa có SDK quảng cáo: `super-ads-integrate`.
+- App đang dùng AdsPro: `adspro-to-superads`.
+- Chỉ đổi giá trị trong config, không đổi version SDK: `super-ads-config`.
+- Chỉ kiểm trước khi phát hành: `super-ads-release-check`.
+- User chưa đồng ý nâng: dừng, không tự nâng; skill chỉ **đề xuất**, không ép.
+
+## 📋 Prerequisites
+- Đã đọc [super-ads-guide](../super-ads-guide/SKILL.md) (định tuyến và [kiểm version](../super-ads-guide/references/sdk-version-check.md)).
+- Có version SuperAds hiện tại của app (file, dòng) và đã hỏi user version đích.
+- MCP `super-ads` kết nối được (`tools/ai_agent_tools/README.md`) cho phần config.
+- Nhánh git riêng cho việc nâng, để xem `git diff` trước khi commit.
+
+## ⚡ Quick Reference
+
+| Cần | Ở đâu |
+|---|---|
+| Từng bước nhảy và chỗ trích dẫn `MIGRATION.md` | [references/upgrade-hops.md](references/upgrade-hops.md) |
+| Mẫu changelog giao user | [templates/changelog-template.md](templates/changelog-template.md) |
+| Cách đọc version app | [../super-ads-guide/references/sdk-version-check.md](../super-ads-guide/references/sdk-version-check.md) |
+| Vòng sửa config có `mustAsk` | [../super-ads-config/SKILL.md](../super-ads-config/SKILL.md) |
+
+Bản hiện tại của repo SDK là `4.0.0` (`super-ads/build.gradle:6`). Bản đích của app: hỏi user, không đoán.
+
+## 🏗️ Recommended Architecture
+> **Not applicable for this skill.**
+
+## Workflow
+1. **Đọc version hiện tại** của app (theo `super-ads-guide`, [sdk-version-check](../super-ads-guide/references/sdk-version-check.md)): core và từng plugin. Hỏi user xác nhận bản đích (bản mới nhất đã publish).
+2. **Đọc `MIGRATION.md`** cho từng bước nhảy từ bản hiện tại tới bản đích (mục 3.x -> 4.0.0 ở đầu file, 2.x -> 3.0.0 và 1.1.x ở phía dưới). Tóm tắt thay đổi bắt buộc theo [references/upgrade-hops.md](references/upgrade-hops.md). Bước nhảy không có mục trong `MIGRATION.md`: dừng và hỏi user, không tự suy luận.
+3. **Lập kế hoạch và xin duyệt trước khi sửa**: liệt kê file sẽ sửa, version sẽ bump, import sẽ đổi, key config sẽ đổi, hành vi đổi. Chờ user duyệt.
+4. **Nâng**:
+   - Gradle: core và **mọi** plugin cùng một version (`MIGRATION.md:7-16`).
+   - Import và logic: theo các bảng trong `MIGRATION.md`; ví dụ `sed` trong đó chỉ là tham khảo, xem `git diff` sau khi chạy.
+   - Config JSON: chỉ qua MCP `super-ads`: `validate_config`, `diff_configs`, `explain_key`, `impact_of_patch`, `apply_patch`. Điểm dừng `mustAsk` và duyệt đúng patch theo [super-ads-config](../super-ads-config/SKILL.md), không lặp lại ở đây.
+5. **Kiểm**: build module app, `validate_config` trên config sau khi sửa, kiểm trên thiết bị theo [super-ads-adb-test](../super-ads-adb-test/SKILL.md); trước khi phát hành theo [super-ads-release-check](../super-ads-release-check/SKILL.md).
+6. **Báo changelog** cho user theo [templates/changelog-template.md](templates/changelog-template.md): SDK từ-lên, import đã đổi, logic đã đổi, key config thêm/xoá/đổi tên, thay đổi hành vi, việc còn lại cho user.
+
+## 🔧 API Reference
+
+| Tool MCP | Mục đích trong skill này |
+|---|---|
+| `validate_config` | Kiểm config hợp lệ sau khi nâng |
+| `diff_configs` | So config trước và sau |
+| `explain_key` | Hiểu một key trước khi đổi |
+| `impact_of_patch` | Tính tác động và `mustAsk` cho đúng patch |
+| `apply_patch` | Áp patch đã được user duyệt |
+
+## ✅ Best Practices
+- Nâng từng bước nhảy một khi bản hiện tại cách xa bản đích; build sau mỗi bước.
+- Đọc `MIGRATION.md` mục tương ứng trước, không dựa vào trí nhớ về SDK.
+- Để compiler chỉ ra import còn sót sau khi sửa theo bảng.
+- Ghi lại mọi thứ đã đổi để đưa vào changelog ngay lúc làm.
+
+## ❌ Anti-patterns
+- Nâng khi user chưa đồng ý, hoặc ép nâng khi user muốn giữ bản cũ.
+- Nâng riêng core hay riêng một plugin: lỗi lúc chạy (`MIGRATION.md:7-16`).
+- Chạy `sed` mù trên toàn repo rồi commit không xem `git diff`.
+- Sửa config JSON tay thay vì MCP, hoặc áp patch khi chưa có duyệt.
+- Tự bịa tên API, key hay version đích không có trong `MIGRATION.md`.
+
+## ⚠️ Common Issues
+
+| Problem | Cause | Solution |
+|---|---|---|
+| `NoClassDefFoundError` lúc chạy | Plugin cũ link `api.plugin.*` với core 4.0.0 (`MIGRATION.md:7-16`) | Nâng mọi plugin cùng bản với core |
+| Import không còn biên dịch | Package đổi ở 4.0.0 | Đổi theo bảng trong `MIGRATION.md`, build lại |
+| Version đích chưa có trên repo Maven | Chưa publish | Dừng, hỏi user (xem `super-ads-integrate/SKILL.md`); không tự hạ bản |
+| `validate_config` báo lỗi sau nâng | Key đổi giữa các bản | `explain_key`, đối chiếu `MIGRATION.md`, vá qua vòng `super-ads-config` |
+
+## Files created
+- Không tạo file nguồn mới cho SDK. Changelog nâng cấp (theo mẫu) có thể được lưu ở nơi user chỉ định; mặc định chỉ báo trong hội thoại.
+
+## Files modified
+- File Gradle của app khai `com.android.fullhd.ads:*`: bump version của core và mọi plugin.
+- File Kotlin/Java của app có import `com.android.fullhd.super_ads` cần đổi theo `MIGRATION.md`, và logic bị ảnh hưởng.
+- File config JSON của app (asset, working config MCP): chỉ qua `apply_patch` đã duyệt, rồi `sync_to_source` theo `AI_ADS_PLAYBOOK.md`.
+- Manifest chỉ khi `MIGRATION.md` nói phải đổi (vd tham chiếu installer ở 3.0.0).
+
+## Verification
+- Build module app bằng Gradle, trích output thật. Không build được thì ghi rõ.
+- `./gradlew :<app>:dependencies --configuration releaseRuntimeClasspath | grep "com.android.fullhd.ads:"`: mọi artifact SuperAds cùng một version.
+- `validate_config` trên config sau nâng: không lỗi.
+- Kiểm thiết bị qua `super-ads-adb-test` (nếu có thiết bị); nếu bỏ qua, ghi là bỏ qua.
+- Log lúc init không có dòng `RequiredPluginCheck` (thiếu `SuperAdsInHouse`).
+
+## Checklist
+- [ ] Có version hiện tại và version đích do user xác nhận.
+- [ ] Đã đọc mục `MIGRATION.md` cho từng bước nhảy.
+- [ ] User duyệt kế hoạch trước khi sửa.
+- [ ] Core và mọi plugin cùng một version.
+- [ ] Import và logic đổi theo `MIGRATION.md`; `git diff` đã xem.
+- [ ] Config đổi qua MCP, có duyệt đúng patch.
+- [ ] Build, `validate_config` đã chạy; kiểm thiết bị đã chạy hoặc ghi rõ bỏ qua.
+- [ ] Đã giao changelog.
+
+## 📈 Performance Notes
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+Nội dung từng bước nhảy nằm ở [references/upgrade-hops.md](references/upgrade-hops.md); nguồn gốc là `MIGRATION.md`.
+
+## Output
+Changelog theo [templates/changelog-template.md](templates/changelog-template.md), kèm: file đã tạo, file đã sửa, tóm tắt thay đổi, lỗi hoặc vấn đề gặp, việc đã chạy và việc bỏ qua.
+
+## Examples
+- Các bước nhảy và cách tóm tắt: [references/upgrade-hops.md](references/upgrade-hops.md).
+- Mẫu báo cáo: [templates/changelog-template.md](templates/changelog-template.md).
+
+## 📚 References
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-config](../super-ads-config/SKILL.md), [super-ads-adb-test](../super-ads-adb-test/SKILL.md), [super-ads-release-check](../super-ads-release-check/SKILL.md), [adspro-to-superads](../adspro-to-superads/SKILL.md).
+- `MIGRATION.md`, `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` ở repo SDK.
+
+## 🏷️ Tags
+`super-ads`, `upgrade`, `migration`, `sdk-version`, `gradle`, `changelog`

package/skills/super-ads-upgrade/references/upgrade-hops.md

@@ -0,0 +1,26 @@
+# Các bước nhảy nâng cấp SuperAds
+
+Nguồn duy nhất: `MIGRATION.md` ở gốc repo SDK. File này chỉ tóm tắt; khi khác nhau, `MIGRATION.md` thắng. Chỉ có các mục dưới đây trong `MIGRATION.md`. Từ bản chưa có mục (vd 1.x tới 2.x): dừng và hỏi user.
+
+## Hop 3.x -> 4.0.0 (đầu `MIGRATION.md`)
+- Chỉ đổi package (vị trí class); không đổi tên class, chữ ký hàm, hành vi, JSON config, tên event, mã lỗi hay trạng thái đã lưu. App chỉ phải đổi import (`MIGRATION.md:3-5`).
+- Bắt buộc: core và mọi plugin cùng 4.0.0; plugin 3.x không chạy với core 4.0.0 (`MIGRATION.md:7-16`).
+- Import app hay dùng đổi theo bảng "Đổi import - class app thường dùng" (`MIGRATION.md:18`); `Ads`, `AdsFeatures`, `api.model.*` giữ nguyên.
+- Hợp đồng plugin `api.plugin` -> `spi`: chỉ ảnh hưởng code tự viết plugin (`MIGRATION.md:39`).
+- Class nội bộ đổi chỗ: app không nên dùng (`MIGRATION.md:57`).
+- Ví dụ `sed` chỉ để tham khảo; xem `git diff`, build để compiler chỉ import còn sót (`MIGRATION.md:74`).
+- Config JSON: không đổi key.
+
+## Hop 2.x -> 3.0.0 (`MIGRATION.md`, mục "2.x -> 3.0.0")
+- Giữ nguyên JSON config, tên event, mã lỗi, trạng thái đã lưu (`MIGRATION.md:93-94`).
+- Core và mọi plugin cùng một version (mục "BẮT BUỘC"); version chung ghi trong mục đó là bản của thời điểm viết, bản đích lấy từ user, không lấy từ đó.
+- Đổi import 3 class public; một hàm kiểm ad test được đổi tên (xem bảng đổi tên trong `MIGRATION.md`); consent trước ad đầu tiên qua `Ads.gdpr.requestAndShowIfRequired(...)`.
+- Bảng thay đổi hành vi (InHouse bỏ BANNER, countdown, nút đóng, `scenarios` bị bỏ qua, mã lỗi `ClientError` gỡ, `NATIVE_FULL_DIALOG` gỡ, ...): `MIGRATION.md:133-152`. Mỗi dòng cần báo user nếu app dính.
+- Tracking Firebase tách sang `super-ads-tracking`; thêm module và cờ `global.tracking.*` nếu app cần (`MIGRATION.md:442-452`).
+- Plugin mạng khai dependency riêng theo từng mạng (mục "BẮT BUỘC: thêm dependency cho từng mạng").
+
+## Hop 1.1.x -> 1.1.4 (`MIGRATION.md:224-229`)
+- Từ 1.1.4 core không chứa mạng quảng cáo nào; AdMob và InHouse là artifact riêng, tự đăng ký qua `ContentProvider`. Cần thêm dependency plugin cho từng mạng đang dùng.
+
+## Cách tóm tắt cho user
+Với mỗi hop, ghi: thay đổi bắt buộc, thay đổi tuỳ chọn, thay đổi hành vi app có thể dính, key config bị ảnh hưởng. Đưa vào kế hoạch ở bước 3 của Workflow trong [../SKILL.md](../SKILL.md). Cách đọc version hiện tại: [../../super-ads-guide/references/sdk-version-check.md](../../super-ads-guide/references/sdk-version-check.md).