@hungvv/super-ads-skills 1.0.0 → 1.1.0

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

@@ -0,0 +1,129 @@
+---
+schema: 1
+name: super-ads-guide
+description: Use when working on anything involving the SuperAds SDK, its ads config JSON or the super-ads MCP
+version: 1.0.0
+group: Ads
+superAds: ">=4.0.0 <5.0.0"
+---
+
+# SuperAds Guide (điểm vào)
+
+Skill điểm vào cho mọi việc liên quan SuperAds: chọn **đúng một skill chủ** cho task, đọc skill đó **trước** khi đụng file, và kiểm version SDK của app trước khi làm theo skill nào khác.
+
+## When to use
+- Bắt đầu bất kỳ task nào có SuperAds, `Ads.*`, file config JSON quảng cáo hoặc MCP `super-ads`.
+- Chưa rõ task thuộc skill nào trong bộ `super-ads-*`.
+- Cần kiểm app đang dùng SuperAds bản nào so với bản mà skill viết cho (`superAds` trong frontmatter).
+- Skill báo app dùng bản SDK thấp hơn khoảng hỗ trợ và cần quyết định có nâng cấp không.
+
+## 🚫 When NOT to use
+- Đã biết rõ skill chủ và đã kiểm version trong phiên này: đọc thẳng skill đó.
+- Code app không liên quan quảng cáo: dùng skill chung của repo app, không phải bộ này.
+
+## 📋 Prerequisites
+> **Not applicable for this skill.**
+
+## ⚡ Quick Reference
+
+| Task | Skill chủ |
+|---|---|
+| App chưa có SDK quảng cáo, gắn SuperAds từ đầu | [super-ads-integrate](../super-ads-integrate/SKILL.md) |
+| App đang dùng AdsPro, chuyển sang SuperAds | [adspro-to-superads](../adspro-to-superads/SKILL.md) |
+| App đã có SuperAds, thêm hoặc đổi vị trí ad | [super-ads-add-placement](../super-ads-add-placement/SKILL.md) |
+| Đổi giá trị, bật tắt, xoá key trong config qua MCP | [super-ads-config](../super-ads-config/SKILL.md) |
+| A/B test config qua Firebase | [super-ads-ab-test](../super-ads-ab-test/SKILL.md) |
+| Ad không hiện, load lỗi, hiển thị sai, crash | [super-ads-debug](../super-ads-debug/SKILL.md) |
+| Đo hoặc giải thích show rate theo placement | [super-ads-show-rate](../super-ads-show-rate/SKILL.md) |
+| Chạy kịch bản kiểm trên thiết bị, không sửa app | [super-ads-adb-test](../super-ads-adb-test/SKILL.md) |
+| Bản debug chạy một lần với config khác asset | [super-ads-debug-override](../super-ads-debug-override/SKILL.md) |
+| Rà trước khi phát hành | [super-ads-release-check](../super-ads-release-check/SKILL.md) |
+| App dùng SuperAds cũ hơn skill cần, hoặc user muốn nâng SuperAds | [super-ads-upgrade](../super-ads-upgrade/SKILL.md) |
+
+Một task có đúng một skill chủ. Skill khác chỉ hỗ trợ (vd thêm placement dùng lại vòng của `super-ads-config`), không giành quyền quyết định phạm vi.
+
+Tài liệu nằm ở đâu:
+- MCP `super-ads` (19 tool) và quy trình config: `tools/ai_agent_tools/README.md`, `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`.
+- Thay đổi giữa các bản SDK: `MIGRATION.md` ở gốc repo SDK (mục mới nhất ở đầu file).
+- Danh mục skill: `tools/super-ads-skills/skills/README.md`.
+- Quy trình kiểm version: [references/sdk-version-check.md](references/sdk-version-check.md). Bảng tương thích: [references/compatibility.md](references/compatibility.md).
+
+## 🏗️ Recommended Architecture
+> **Not applicable for this skill.**
+
+## Workflow
+1. **Chọn skill chủ** theo bảng ở Quick Reference. Không khớp một hàng nào hoặc khớp hai: hỏi user, nêu 2-3 lựa chọn kèm đề xuất.
+2. **Kiểm version SDK của app** (đầy đủ ở [references/sdk-version-check.md](references/sdk-version-check.md)): đọc version `SuperAds` khai trong Gradle của app, so với `superAds` trong frontmatter skill chủ.
+3. **Version trong khoảng**: đọc skill chủ và làm theo.
+4. **Version thấp hơn khoảng**: không làm tiếp một cách im lặng. Báo user, **đề xuất** `super-ads-upgrade` để nâng core và mọi plugin cùng một bản mới nhất, rồi cập nhật logic, key JSON, config, kèm changelog. Chỉ nâng khi user đồng ý. User từ chối thì nói rõ phần nào của skill có thể không đúng với bản của họ, rồi hỏi có tiếp tục không.
+5. **Version cao hơn khoảng**: báo rằng skill có thể đã cũ, dựa vào `MIGRATION.md` và code SDK, không dựa vào skill khi hai bên lệch.
+6. **Sửa config thì qua MCP `super-ads` trước**, theo `super-ads-config`. Không sửa JSON tay khi MCP làm được.
+7. Kết thúc, báo đúng những gì đã chạy (xem Output).
+
+## 🔧 API Reference
+> **Not applicable for this skill.**
+
+## ✅ Best Practices
+- Đọc skill chủ trước khi viết code hay sửa config, không đọc sau.
+- Dùng MCP `super-ads` cho mọi thay đổi config; chỉ rơi về sửa file khi MCP không phủ.
+- Gặp điểm dừng `mustAsk` của `impact_of_patch`: dừng, hỏi nguyên văn từng câu trong `askReasons`, chờ trả lời rõ (xem `super-ads-config`).
+- Không chắc thì hỏi: nêu 2-3 lựa chọn và một đề xuất.
+- Báo đúng việc đã chạy: lệnh nào, output nào. Bước bỏ qua ghi là bỏ qua.
+
+## ❌ Anti-patterns
+- Đoán tên key, format, network, layout hay API `Ads.*` không có trong schema MCP, `MIGRATION.md` hoặc code SDK.
+- Áp patch chỉ vì `mustAsk = false`: vẫn cần user duyệt đúng patch đó.
+- Tự nâng version SuperAds khi user chưa đồng ý, hoặc nâng riêng core mà không nâng plugin.
+- Làm theo skill viết cho bản mới trên app dùng bản cũ mà không báo user.
+- Khẳng định build, test hay kiểm thiết bị đã qua khi chưa chạy.
+
+## ⚠️ Common Issues
+
+| Problem | Cause | Solution |
+|---|---|---|
+| Không tìm thấy dòng version SuperAds | Version nằm ở biến, `libs.versions.toml` hoặc module khác | Làm theo [references/sdk-version-check.md](references/sdk-version-check.md); vẫn không thấy thì hỏi user |
+| Core và plugin lệch version | Nâng một phần | `NoClassDefFoundError` / `NoSuchMethodError` lúc chạy (`MIGRATION.md:7-16`); nâng cùng bản qua `super-ads-upgrade` |
+| Hai skill cùng khớp task | Task gồm nhiều phần | Chọn skill chủ cho phần quyết định phạm vi, hỏi user nếu vẫn mơ hồ |
+
+## Files created
+This skill does not create source files.
+
+## Files modified
+This skill does not modify source files.
+
+## Verification
+- Đã nêu tên skill chủ và lý do chọn.
+- Đã ghi version SuperAds đọc được của app (kèm file, dòng) và so với khoảng `superAds` của skill chủ.
+- Nếu version thấp hơn: đã báo user và hỏi ý kiến về `super-ads-upgrade`, chưa tự nâng.
+
+## Checklist
+- [ ] Chọn đúng một skill chủ, đã mở `SKILL.md` của nó.
+- [ ] Đã đọc version SuperAds của app và so với khoảng `superAds`.
+- [ ] Version thấp hơn thì đã đề xuất `super-ads-upgrade`, chờ user.
+- [ ] Config đi qua MCP `super-ads`, có duyệt đúng patch.
+- [ ] Không đoán key, API hay coordinate; chỗ không chắc đã hỏi.
+- [ ] Báo cáo ghi đúng điều đã chạy.
+
+## 📈 Performance Notes
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+> **Not applicable for this skill.**
+
+## Output
+Báo user: skill chủ đã chọn; version SuperAds của app và kết quả so với khoảng skill hỗ trợ; quyết định về nâng cấp (nếu có); các việc đã chạy và việc đã bỏ qua.
+
+## Examples
+- Bảng tương thích skill và bản SuperAds: [references/compatibility.md](references/compatibility.md).
+- Quy trình đọc và so version, kèm ca lệch: [references/sdk-version-check.md](references/sdk-version-check.md).
+
+## 📚 References
+- [super-ads-upgrade](../super-ads-upgrade/SKILL.md): nâng SuperAds khi version thấp hơn.
+- [super-ads-config](../super-ads-config/SKILL.md): vòng sửa config và các điểm dừng `mustAsk`.
+- `MIGRATION.md`, `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`, `tools/ai_agent_tools/README.md` ở repo SDK.
+
+## 🏷️ Tags
+`super-ads`, `router`, `entry-point`, `sdk-version`, `routing`, `mcp`

package/skills/super-ads-guide/references/compatibility.md

@@ -0,0 +1,26 @@
+# Bảng tương thích skill và SuperAds
+
+Mọi skill trong bộ `super-ads-*` khai `superAds: ">=4.0.0 <5.0.0"` trong frontmatter, nghĩa là viết và kiểm cho SuperAds 4.x (bản hiện tại của repo SDK: `4.0.0`, `super-ads/build.gradle:6`).
+
+| Skill | superAds | Version skill |
+|---|---|---|
+| super-ads-guide | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-upgrade | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-integrate | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| adspro-to-superads | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-add-placement | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-config | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-ab-test | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-debug | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-show-rate | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-adb-test | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-debug-override | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+| super-ads-release-check | `>=4.0.0 <5.0.0` | xem frontmatter `SKILL.md` |
+
+Cột "Version skill" không chép số ở đây để khỏi lệch: số thật nằm trong `version:` của frontmatter từng `SKILL.md`.
+
+## Cách dùng
+- Version SuperAds của app nằm trong khoảng: dùng skill bình thường.
+- Thấp hơn khoảng: xem bước 4 của Workflow trong [../SKILL.md](../SKILL.md) và [sdk-version-check.md](sdk-version-check.md).
+- Cao hơn khoảng: skill có thể cũ; xem mục "Version cao hơn" trong [sdk-version-check.md](sdk-version-check.md).
+- Khi bump khoảng `superAds` của một skill (sau khi kiểm skill với bản SDK mới), cập nhật cả bảng này.

package/skills/super-ads-guide/references/sdk-version-check.md

@@ -0,0 +1,50 @@
+# Kiểm version SuperAds của app
+
+Mục tiêu: biết app đang dùng SuperAds bản nào, so với khoảng `superAds` trong frontmatter của skill sắp dùng, và quyết định dừng hay tiếp tục. Chỉ đọc, không sửa file.
+
+## 1. Đọc version từ Gradle của app
+
+Artifact SuperAds có group `com.android.fullhd.ads`. Mẫu khai trong repo (`super-ads-integrate/references/gradle-setup.md`, mục 2 và `MIGRATION.md:9-16`):
+
+```gradle
+def superAds = '4.0.0'
+implementation "com.android.fullhd.ads:SuperAds:$superAds"
+implementation "com.android.fullhd.ads:SuperAdsAdmob:$superAds"
+```
+
+Việc cần làm:
+1. Tìm trong file Gradle của module app (và file Gradle gốc, các file `apply from`) dòng chứa `com.android.fullhd.ads:SuperAds`. Repo không chỉ định tên file cố định cho app thật, nên tìm bằng grep, không đoán file.
+2. Dòng dùng biến (như `$superAds`): lần theo biến tới chỗ gán `def superAds = '...'` hoặc tương đương. Version khai thẳng trong chuỗi thì đọc tại chỗ. Repo không mô tả version catalog, nên nếu dependency nằm ở nơi khác (catalog, `buildSrc`, convention plugin), đọc đúng nơi đó hoặc hỏi user.
+3. Xác nhận bằng Gradle khi build chạy được (lệnh từ `gradle-setup.md`, mục 1b; thay `<app>` bằng tên module app):
+
+```bash
+./gradlew :<app>:dependencies --configuration releaseRuntimeClasspath | grep "com.android.fullhd.ads:"
+```
+
+4. Ghi lại: file, dòng, version của `SuperAds` và của từng plugin (`SuperAdsAdmob`, `SuperAdsInHouse`, ...). `SuperAdsContract` có version riêng (`1.0.0-alpha`), không tính vào so sánh.
+5. Core và mọi plugin phải cùng một version (`MIGRATION.md:7-16`). Lệch nhau là lỗi cần báo ngay, kể cả khi core nằm trong khoảng.
+
+Không tìm thấy dòng nào: hỏi user, không giả định bản.
+
+## 2. So với khoảng `superAds` của skill
+
+Khoảng nằm trong frontmatter skill (hiện `>=4.0.0 <5.0.0`).
+
+| Kết quả | Việc làm |
+|---|---|
+| Trong khoảng | Tiếp tục với skill chủ |
+| Thấp hơn | Mục 3 |
+| Cao hơn | Mục 4 |
+| Core và plugin lệch version | Báo user; đề xuất `super-ads-upgrade` đưa tất cả về cùng một bản |
+
+## 3. Version thấp hơn khoảng
+
+Không tiếp tục im lặng.
+1. Báo user: app đang dùng bản `X`, skill viết cho `>=4.0.0 <5.0.0`.
+2. **Đề xuất** dùng [super-ads-upgrade](../../super-ads-upgrade/SKILL.md) để nâng lên bản SuperAds mới nhất, core và mọi plugin cùng một bản, sau đó cập nhật logic, key JSON và config, kèm changelog.
+3. Chờ user đồng ý. Không nâng khi chưa có đồng ý rõ.
+4. User từ chối: nêu phần nào của skill có thể sai với bản của họ (import, key config, API) rồi hỏi có tiếp tục với rủi ro đó không. Không tự suy luận khác biệt; đối chiếu `MIGRATION.md`.
+
+## 4. Version cao hơn khoảng
+
+Skill có thể đã cũ so với SDK. Báo user, rồi dựa vào `MIGRATION.md` (mục mới nhất ở đầu file) và code SDK khi skill và SDK khác nhau. Đừng áp quy tắc của skill lên phần SDK đã đổi.

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

@@ -1,54 +1,62 @@
 ---
 schema: 1
 name: super-ads-integrate
-description: Use when an Android app has no ads SDK yet (or a fresh module) and needs SuperAds wired in — Gradle artifacts, manifest keys, Application init, consent, premium, first config and first placement.
-version: 1.0.0
+description: Use when an app has no ads SDK yet and needs SuperAds wired in - Gradle, manifest, init, consent, first config
+version: 1.1.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Gắn SuperAds vào app mới
 
 Đưa app từ "chưa có ads" tới "placement đầu tiên chạy được và đã kiểm trên máy". Mỗi bước đụng Gradle, manifest hoặc `Application` đều phải được user duyệt trước.
 
-| Bước | Tài liệu |
-|---|---|
-| Artifact, version, Next-Gen, manifest | [references/gradle-setup.md](references/gradle-setup.md) |
-| `Application`, init, consent, premium | [references/application-setup.md](references/application-setup.md) |
-| Bật log | [../super-ads-debug/references/logging-setup.md](../super-ads-debug/references/logging-setup.md) |
-| Placement đầu tiên | `super-ads-add-placement` |
-| Quy trình MCP config | `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` |
-
 ## When to use
+
 - App chưa có SDK quảng cáo nào, hoặc module mới cần SuperAds.
 
-## When NOT to use
+## 🚫 When NOT to use
+
 - App còn AdsPro → `adspro-to-superads`.
-- App đã có SuperAds, chỉ thêm vị trí → `super-ads-add-placement`.
-- Nâng SuperAds 3.x lên 4.0.0 (đổi package, sửa import) hoặc 2.x lên 3.0.0 → làm theo `MIGRATION.md` (skill nâng cấp chưa có).
+- App đã có SuperAds, chỉ thêm vị trí → [super-ads-add-placement](../super-ads-add-placement/SKILL.md).
+- Nâng SuperAds 3.x lên 4.0.0 (đổi package, sửa import) hoặc 2.x lên 3.0.0 → [super-ads-upgrade](../super-ads-upgrade/SKILL.md) (theo `MIGRATION.md`).
 - App đang dùng SDK quảng cáo khác (AppLovin/IronSource trực tiếp, wrapper riêng…): Stop, hỏi user về phạm vi thay thế.
 
-## Authority order
-1. Code SDK và Gradle của repo SDK.
-2. `MIGRATION.md`.
-3. Tài liệu skill. `app/` trong repo SDK chỉ là **ví dụ**: không chép App ID, key, unit, tên config của nó.
+## 📋 Prerequisites
 
-## Contract
-**MUST**
-- Core và mọi plugin cùng một version (`MIGRATION.md:7-16`).
-- Chỉ thêm plugin network mà config thật sự dùng, **trừ bộ nền luôn thêm**: `SuperAdsInHouse` và `SuperAdsDebug` (`implementation`), `SuperAdsDebugOverride` (`debugImplementation`) ([gradle-setup.md](references/gradle-setup.md) mục 1b).
-- Logger được init trước `Ads.init`; bản release tắt hoặc chỉ `WARN` trở lên.
-- `isDebug = BuildConfig.DEBUG` (hoặc tương đương). Bản release phải là `false`, vì `true` thay unit AdMob bằng unit test (`super-ads/src/main/java/com/android/fullhd/super_ads/engine/load/AdItemLoader.kt:64`).
-- Consent chạy và có kết quả **trước** preload/show đầu tiên (`MIGRATION.md:126-127`).
-- Config đầu tiên tạo bằng MCP `super-ads` (`create_config` / `create_ad` → `validate_config` → `sync_to_source`).
-- Build module app sau mỗi bước Gradle và trích output thật.
+- Định tuyến skill và kiểm version SDK: [super-ads-guide](../super-ads-guide/SKILL.md).
+- Quy tắc version: skill này nhắm SuperAds `>=4.0.0 <5.0.0`. App chưa có SDK nên cài **bản 4.x mới nhất**. Nếu app đã có SuperAds bản thấp hơn, dừng lại 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.
+- Thứ tự nguồn sự thật: (1) code SDK và Gradle của repo SDK, (2) `MIGRATION.md`, (3) tài liệu skill. `app/` trong repo SDK chỉ là **ví dụ**: không chép App ID, key, unit, tên config của nó.
+- Có từ user trước khi viết Gradle/manifest: AdMob App ID, ad unit id (hoặc key của network khác), network sẽ dùng, GMS cổ điển hay Next-Gen, quyền truy cập repo Maven chứa artifact SuperAds.
+
+## ⚡ Quick Reference
+
+| Cần | Mở |
+|---|---|
+| Artifact, version, bộ nền, Next-Gen, manifest | [references/gradle-setup.md](references/gradle-setup.md) |
+| `Application`, ba cách init, consent, premium | [references/application-setup.md](references/application-setup.md) |
+| Mẫu khai dependency để copy | [templates/gradle-dependencies.md](templates/gradle-dependencies.md) |
+| Mẫu `Application.onCreate` để copy | [templates/application-oncreate.md](templates/application-oncreate.md) |
+| Consent UMP ở Activity đầu | [snippets/consent-request.md](snippets/consent-request.md) |
+| Bật log | [../super-ads-debug/references/logging-setup.md](../super-ads-debug/references/logging-setup.md) |
+| Placement đầu tiên | [super-ads-add-placement](../super-ads-add-placement/SKILL.md) |
+| Quy trình MCP config | `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` |
+
+## 🏗️ Recommended Architecture
 
-**MUST NOT**
-- Không thêm dependency, repo Maven, meta-data khi user chưa đồng ý.
-- Không bịa App ID, SDK key, ad unit id.
-- Không trộn `SuperAdsAdmobNextGen` với `SuperAdsAdmob` hoặc `SuperAdsArbiter` (`MIGRATION.md:160-172`).
-- Không đặt `Ads.show` ở `Application`, trừ App Open qua `AppLifecycleMonitor`.
+Thứ tự lắp, mỗi tầng chỉ làm sau khi tầng trước đã build/chạy được:
+
+1. Gradle: core + bộ nền (`SuperAdsInHouse`, `SuperAdsDebug`, `SuperAdsDebugOverride`) + plugin network theo config, cùng version.
+2. Manifest: meta-data cho từng network.
+3. `Application`: logger → `Ads.init`.
+4. Config đầu tiên: tạo bằng MCP `super-ads`, sync vào đúng file asset app nạp.
+5. Consent ở Activity đầu, rồi mới preload/show; premium đặt lại mỗi lần khởi động.
+6. Placement đầu tiên qua `super-ads-add-placement`.
+
+## Workflow
+
+### Stop conditions (dừng và hỏi user)
 
-## Stop conditions (dừng và hỏi user)
 - Chưa có AdMob App ID, ad unit id, hoặc key của network khác.
 - Chưa chọn network, hoặc chưa chọn GMS cổ điển hay Next-Gen.
 - Không truy cập được repo Maven chứa artifact SuperAds.
@@ -59,48 +67,103 @@ group: Ads
 - Repo Maven không có đủ artifact đúng version (`SuperAdsUmp`, `SuperAdsAdmobNextGen`, `SuperAdsTracking`…).
 - Chưa rõ app xử lý thế nào khi consent trả `canRequestAds = false`, `Error` hoặc `Timeout` ([application-setup.md](references/application-setup.md) mục 3).
 
-## Phase 1: Khảo sát
+### 1. Khảo sát
+
 1. Module app, `minSdk`, `compileSdk`, phiên bản Kotlin/AGP, cách khai dependency (version catalog hay `build.gradle`).
 2. SDK quảng cáo / Firebase sẵn có: grep `play-services-ads`, `com.google.android.gms.ads`, `applovin`, `ironsource`.
 3. `Application` đã có chưa, Activity đầu tiên là màn nào (splash?).
 4. Danh sách network, App ID, unit: hỏi user.
 5. Có cần tracking Firebase không, app đã có Firebase (google-services) chưa: hỏi user.
 
-**Verify:** có bảng: module, network, cách init, Activity đầu tiên, các giá trị còn thiếu.
+### 2. Gradle và manifest
 
-## Phase 2: Gradle và manifest
-- Theo [gradle-setup.md](references/gradle-setup.md): core + **bộ nền (mục 1b: InHouse, Debug, DebugOverride)** + plugin network theo config, cùng version + layout; Next-Gen nếu được chọn; `SuperAdsTracking` nếu user chọn tracking.
+- Theo [gradle-setup.md](references/gradle-setup.md): core + **bộ nền (mục 1b: InHouse, Debug, DebugOverride)** + plugin network theo config, cùng version + layout; Next-Gen nếu được chọn; `SuperAdsTracking` nếu user chọn tracking. Mẫu: [templates/gradle-dependencies.md](templates/gradle-dependencies.md).
 - Thêm meta-data cho từng network.
 - `./gradlew :<appModule>:assembleDebug`.
 
-**Verify:** build pass. `./gradlew :<appModule>:dependencies --configuration debugRuntimeClasspath` cho thấy mọi artifact `com.android.fullhd.ads` cùng version, trừ `SuperAdsContract` (version riêng, xem gradle-setup.md mục 2), và có đủ `SuperAdsInHouse`, `SuperAdsDebug`, `SuperAdsDebugOverride`. Cấu hình `releaseRuntimeClasspath` có `SuperAdsInHouse` + `SuperAdsDebug`, không có `SuperAdsDebugOverride`.
+### 3. Application
 
-## Phase 3: Application
-- Theo [application-setup.md](references/application-setup.md) mục 1–2: logger → init.
+- Theo [application-setup.md](references/application-setup.md) mục 1–2: logger → init. Mẫu: [templates/application-oncreate.md](templates/application-oncreate.md).
 - Trước khi tạo config: `read_working_config` (MCP), xem `defaultSyncPath`. Server lấy đích từ `MCP_SUPER_ADS_PROJECT_ROOT` + `MCP_SUPER_ADS_CONFIG`; không set `MCP_SUPER_ADS_CONFIG` thì nó tự tạo file rỗng `app/src/main/assets/tmp-*.json` (`tools/ai_agent_tools/README.md:61-62`). `defaultSyncPath` phải là file asset của đúng module app, cùng tên với file truyền cho `Ads.init`; không khớp thì truyền `targetPath` (phải nằm trong project root, `tools/ai_agent_tools/src/mcp/tools.js:94-101`) hoặc nhờ user khởi động lại MCP với env đúng.
 - Tạo config đầu tiên bằng MCP (`create_config`, rồi `create_ad` cho placement đầu), `validate_config`, user xem, `sync_to_source` vào đúng file app sẽ nạp. Xong thì xoá các file `tmp-*.json` do MCP tự sinh trong `assets/` (nếu có), vì Gradle sẽ đóng gói chúng vào APK (`tools/ai_agent_tools/README.md:66-70`); xoá file là việc cần user đồng ý.
 
-**Verify:** chạy bản debug, `adb logcat -s SuperAdsSDK:V` có log init và không có `ConfigRegistryCheck` báo thiếu plugin: cả dòng "KHÔNG có AdNetworkPlugin nào register" (`super-ads/src/main/java/com/android/fullhd/super_ads/config/validate/ConfigRegistryCheck.kt:33-35`) lẫn "no PROVIDER for (…)" cho từng network/format (`super-ads/src/main/java/com/android/fullhd/super_ads/config/validate/ConfigRegistryCheck.kt:88`).
+### 4. Consent và premium
 
-## Phase 4: Consent và premium
-- Consent ở Activity đầu, gom mọi preload/show vào sau callback ([application-setup.md](references/application-setup.md) mục 3).
+- Consent ở Activity đầu, gom mọi preload/show vào sau callback ([application-setup.md](references/application-setup.md) mục 3). Snippet: [snippets/consent-request.md](snippets/consent-request.md).
 - Premium: đặt `Ads.isPremium` mỗi lần khởi động theo trạng thái mua (mục 4).
 
-**Verify:** trong log, không có `ProviderTracker info=bắt đầu load` nào xuất hiện trước khi callback consent chạy.
+### 5. Placement đầu tiên
 
-## Phase 5: Placement đầu tiên
-Chuyển sang `super-ads-add-placement` (call site + kiểm trên máy bằng `super-ads-adb-test`).
+Chuyển sang [super-ads-add-placement](../super-ads-add-placement/SKILL.md) (call site + kiểm trên máy bằng `super-ads-adb-test`).
 
-**Verify:** có Impression của placement đầu tiên trên máy, hoặc ghi rõ chưa kiểm.
+## 🔧 API Reference
 
-## Anti-patterns
+| API / tool | Mục đích | Chi tiết |
+|---|---|---|
+| `Ads.logger.init` | Init logger trước `Ads.init` | [application-setup.md](references/application-setup.md) mục 1 |
+| `Ads.init` | Init SDK, ba cách (asset / provider / asset + Remote Config) | [application-setup.md](references/application-setup.md) mục 2 |
+| `Ads.gdpr.requestAndShowIfRequired` | Consent UMP | [application-setup.md](references/application-setup.md) mục 3 |
+| `Ads.isPremium` | Chặn mọi lần show khi user đã mua | [application-setup.md](references/application-setup.md) mục 4 |
+| MCP `create_config` / `create_ad` / `validate_config` / `sync_to_source` | Tạo và ghi config đầu tiên | `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` |
+
+## ✅ Best Practices
+
+- Core và mọi plugin cùng một version (`MIGRATION.md:7-16`).
+- Chỉ thêm plugin network mà config thật sự dùng, **trừ bộ nền luôn thêm**: `SuperAdsInHouse` và `SuperAdsDebug` (`implementation`), `SuperAdsDebugOverride` (`debugImplementation`) ([gradle-setup.md](references/gradle-setup.md) mục 1b).
+- Logger được init trước `Ads.init`; bản release tắt hoặc chỉ `WARN` trở lên.
+- `isDebug = BuildConfig.DEBUG` (hoặc tương đương). Bản release phải là `false`, vì `true` thay unit AdMob bằng unit test (`super-ads/src/main/java/com/android/fullhd/super_ads/engine/load/AdItemLoader.kt:64`).
+- Consent chạy và có kết quả **trước** preload/show đầu tiên (`MIGRATION.md:126-127`).
+- Config đầu tiên tạo bằng MCP `super-ads` (`create_config` / `create_ad` → `validate_config` → `sync_to_source`).
+- Build module app sau mỗi bước Gradle và trích output thật.
+
+## ❌ Anti-patterns
+
+- Thêm dependency, repo Maven, meta-data khi user chưa đồng ý.
+- Bịa App ID, SDK key, ad unit id.
+- Trộn `SuperAdsAdmobNextGen` với `SuperAdsAdmob` hoặc `SuperAdsArbiter` (`MIGRATION.md:160-172`).
+- Đặt `Ads.show` ở `Application`, trừ App Open qua `AppLifecycleMonitor`.
 - Khai `SuperAds:4.0.0` nhưng plugin `3.x` hoặc cũ hơn (crash lúc chạy, không lỗi lúc build).
 - Gọi `Ads.init` trong Activity.
 - `isDebug = true` cố định.
 - Preload ngay trong `Application.onCreate` trước consent.
 - Chép config, App ID từ app mẫu sang app thật.
 
+## ⚠️ Common Issues
+
+**Log init có dòng `RequiredPluginCheck`.**
+Cause: thiếu `SuperAdsInHouse` (bộ nền). Solution: khai đủ bộ nền ([gradle-setup.md](references/gradle-setup.md) mục 1b).
+
+**Crash lúc chạy (`NoClassDefFoundError` / `NoSuchMethodError`) dù build pass.**
+Cause: core và plugin khác version. Solution: đưa mọi artifact về cùng version, trừ `SuperAdsContract` ([gradle-setup.md](references/gradle-setup.md) mục 2).
+
+**Mất `ad_impression` / `ad_click` dù config bật tracking, hoặc chỉ thấy WARN.**
+Cause: thiếu `SuperAdsTracking`, hoặc app chưa cấu hình Firebase (google-services). Solution: xem `SuperAdsTracking` trong [gradle-setup.md](references/gradle-setup.md) mục 1.
+
+## Files created
+
+- Config đầu tiên: file JSON trong `assets/` của module app, do MCP `sync_to_source` ghi, cùng tên với file truyền cho `Ads.init`.
+- `Application` của app, nếu app chưa có (Bước 1 khảo sát).
+- Không tạo file `tmp-*.json`: file do MCP tự sinh phải được xoá (cần user đồng ý).
+
+## Files modified
+
+- Gradle của module app (và version catalog nếu có): core, bộ nền, plugin network, `SuperAdsTracking` nếu chọn.
+- `AndroidManifest.xml`: meta-data cho từng network (và `android:name` của `Application` nếu vừa tạo).
+- `Application`: logger → `Ads.init` (và `Ads.isPremium` theo trạng thái mua).
+- Activity đầu tiên: consent, gom preload/show sau callback.
+
+## Verification
+
+Báo output thật, không tóm tắt khi chưa chạy. Sau mỗi bước ở Workflow:
+
+1. **Khảo sát:** có bảng: module, network, cách init, Activity đầu tiên, các giá trị còn thiếu.
+2. **Gradle và manifest:** build pass. `./gradlew :<appModule>:dependencies --configuration debugRuntimeClasspath` cho thấy mọi artifact `com.android.fullhd.ads` cùng version, trừ `SuperAdsContract` (version riêng, xem gradle-setup.md mục 2), và có đủ `SuperAdsInHouse`, `SuperAdsDebug`, `SuperAdsDebugOverride`. Cấu hình `releaseRuntimeClasspath` có `SuperAdsInHouse` + `SuperAdsDebug`, không có `SuperAdsDebugOverride`.
+3. **Application:** chạy bản debug, `adb logcat -s SuperAdsSDK:V` có log init và không có `ConfigRegistryCheck` báo thiếu plugin: cả dòng "KHÔNG có AdNetworkPlugin nào register" (`super-ads/src/main/java/com/android/fullhd/super_ads/config/validate/ConfigRegistryCheck.kt:33-35`) lẫn "no PROVIDER for (…)" cho từng network/format (`super-ads/src/main/java/com/android/fullhd/super_ads/config/validate/ConfigRegistryCheck.kt:88`).
+4. **Consent và premium:** trong log, không có `ProviderTracker info=bắt đầu load` nào xuất hiện trước khi callback consent chạy.
+5. **Placement đầu tiên:** có Impression của placement đầu tiên trên máy, hoặc ghi rõ chưa kiểm.
+
 ## Checklist
+
 - [ ] Network, App ID, unit đã có từ user.
 - [ ] Artifact cùng version (trừ `SuperAdsContract`), build pass (trích output).
 - [ ] Đã hỏi về tracking Firebase; thêm `SuperAdsTracking` nếu cần.
@@ -111,5 +174,40 @@ Chuyển sang `super-ads-add-placement` (call site + kiểm trên máy bằng `s
 - [ ] Config tạo bằng MCP, `validate_config` sạch.
 - [ ] Placement đầu tiên đã kiểm (hoặc ghi rõ chưa).
 
+## 📈 Performance Notes
+
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+
+- Không chép App ID, SDK key, ad unit id từ app mẫu sang app thật; giá trị do user cung cấp.
+- `isDebug = true` thay mọi unit AdMob bằng unit test và ép vùng EEA cho UMP: bản release phải là `false`.
+- Consent phải có kết quả trước request ad đầu tiên; core không tự chặn hộ.
+
+## 🔄 Migration Guide
+
+> **Not applicable for this skill.**
+
 ## Output
+
 File đã sửa (Gradle, manifest, `Application`, Activity đầu, config), output build, kết quả chạy trên máy, các giá trị còn chờ user, phần chưa xác minh.
+
+## Examples
+
+- Mẫu Gradle: [templates/gradle-dependencies.md](templates/gradle-dependencies.md).
+- Mẫu `Application.onCreate`: [templates/application-oncreate.md](templates/application-oncreate.md).
+- Consent ở Activity đầu: [snippets/consent-request.md](snippets/consent-request.md).
+- Mẫu thật trong app ví dụ: xem trích dẫn ở [application-setup.md](references/application-setup.md).
+
+## 📚 References
+
+- [super-ads-guide](../super-ads-guide/SKILL.md): định tuyến, kiểm version SDK.
+- [super-ads-upgrade](../super-ads-upgrade/SKILL.md): nâng cấp SuperAds.
+- [super-ads-add-placement](../super-ads-add-placement/SKILL.md): placement đầu tiên.
+- [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), [super-ads-debug](../super-ads-debug/SKILL.md).
+- `adspro-to-superads`: app còn AdsPro.
+- Repo SDK: `MIGRATION.md`, `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`.
+
+## 🏷️ Tags
+
+`superads`, `integrate`, `gradle`, `application`, `consent`, `onboarding`

package/skills/super-ads-integrate/references/application-setup.md

@@ -4,19 +4,7 @@
 
 ## 1. Thứ tự trong `Application.onCreate`
 
-```kotlin
-override fun onCreate() {
-    super.onCreate()
-    // 1. Logger trước init để thấy log lúc init. Bản release: enabled = false hoặc minLevel = WARN.
-    Ads.logger.init(LogConfig(enabled = BuildConfig.DEBUG, minLevel = LogLevel.FLOW), debug = BuildConfig.DEBUG)
-
-    // 2. Init: chọn MỘT trong ba cách ở mục 2.
-    Ads.init(this, "<config>.json", isDebug = BuildConfig.DEBUG)
-
-    // 3. Tracking (tuỳ chọn, theo yêu cầu của app): module `super-ads-tracking` (chỉ cần thêm dependency, tự cài; bật/tắt bằng `global.tracking.*`), ...
-    // 4. App Open (nếu có): AppLifecycleMonitor(...).register()  — xem super-ads-add-placement
-}
-```
+Mẫu: [../templates/application-oncreate.md](../templates/application-oncreate.md).
 
 - Logger: [../../super-ads-debug/references/logging-setup.md](../../super-ads-debug/references/logging-setup.md). Mẫu thật: logger `app/src/main/java/com/android/hd/ads2026/MyApplication.kt:28-42`, init `app/src/main/java/com/android/hd/ads2026/MyApplication.kt:54-56` (`initRemote` + `refreshRemoteConfig`).
 - `isDebug = true` thay **mọi unit AdMob** bằng unit test của Google lúc load (`SA/engine/load/AdItemLoader.kt:28`, `SA/engine/load/AdItemLoader.kt:64`, `SA/runtime/SdkGraph.kt:117`). Network khác giữ unit gốc (`SA/engine/load/AdItemLoader.kt:138`). Nó cũng bật ghi log ra file mặc định (`SA/runtime/SdkRuntime.kt:259`). Bản release phải là `false`.
@@ -38,14 +26,7 @@ Gọi `Ads.show` trước khi init xong thì SDK xếp hàng chờ (`SA/api/Ads.
 
 ## 3. Consent (UMP)
 
-```kotlin
-// Activity đầu tiên (splash/main), TRƯỚC preload/show đầu tiên
-Ads.gdpr.requestAndShowIfRequired(this, isDebug = BuildConfig.DEBUG) { result ->
-    // result: Success(status, canShowAds, canRequestAds) | Error(message) | Timeout
-    // Xử lý canRequestAds = false / Error / Timeout là quyết định của app: hỏi user (SDK không chặn hộ).
-    startAdsFlow()   // preload / show / điều hướng tiếp
-}
-```
+Snippet: [../snippets/consent-request.md](../snippets/consent-request.md).
 
 - Core **không tự chặn** request khi chưa có consent (`MIGRATION.md:126-127`). Gọi sai thứ tự nghĩa là app gửi request ad trước khi có consent.
 - Không có plugin cung cấp consent thì callback trả ngay `NOT_REQUIRED` (`SA/api/AdsFeatures.kt:215-239`). Tham số còn có `timeoutMs` (mặc định 10000).

package/skills/super-ads-integrate/references/gradle-setup.md

@@ -40,19 +40,7 @@ Mọi app dùng SuperAds khai đủ bộ nền dưới đây, **kể cả khi co
 
 ## 2. Mẫu (GMS cổ điển)
 
-```gradle
-def superAds = '4.0.0'
-implementation "com.android.fullhd.ads:SuperAds:$superAds"
-// bộ nền (mục 1b): luôn khai
-implementation "com.android.fullhd.ads:SuperAdsInHouse:$superAds"
-implementation "com.android.fullhd.ads:SuperAdsDebug:$superAds"
-debugImplementation "com.android.fullhd.ads:SuperAdsDebugOverride:$superAds"
-// plugin network theo config
-implementation "com.android.fullhd.ads:SuperAdsAdmob:$superAds"
-// plugin khác: cùng $superAds
-implementation "com.android.fullhd.ads:SuperAdsTracking:$superAds"   // chỉ khi app cần tracking Firebase (user đã chọn)
-implementation 'com.android.fullhd.layout:SuperAdsLayout:<version>'
-```
+Mẫu khai dependency (copy rồi chỉnh theo config): [../templates/gradle-dependencies.md](../templates/gradle-dependencies.md).
 
 **Core và mọi plugin phải cùng một version**: package API/SPI đổi ở 4.0.0 (`api.plugin` → `spi`), trộn bản sẽ lỗi lúc chạy (`NoClassDefFoundError` / `NoSuchMethodError`) (`MIGRATION.md:7-16`).
 

package/skills/super-ads-integrate/snippets/consent-request.md

@@ -0,0 +1,12 @@
+# Consent (UMP) ở Activity đầu tiên
+
+> Chạy TRƯỚC preload/show đầu tiên. Quy tắc, `ConsentResult`, mẫu thật: [../references/application-setup.md](../references/application-setup.md) mục 3.
+
+```kotlin
+// Activity đầu tiên (splash/main), TRƯỚC preload/show đầu tiên
+Ads.gdpr.requestAndShowIfRequired(this, isDebug = BuildConfig.DEBUG) { result ->
+    // result: Success(status, canShowAds, canRequestAds) | Error(message) | Timeout
+    // Xử lý canRequestAds = false / Error / Timeout là quyết định của app: hỏi user (SDK không chặn hộ).
+    startAdsFlow()   // preload / show / điều hướng tiếp
+}
+```

package/skills/super-ads-integrate/templates/application-oncreate.md

@@ -0,0 +1,17 @@
+# Mẫu `Application.onCreate`
+
+> Thứ tự: logger trước init, rồi init, rồi tracking / App Open. Giải thích, ba cách init, mẫu thật: [../references/application-setup.md](../references/application-setup.md).
+
+```kotlin
+override fun onCreate() {
+    super.onCreate()
+    // 1. Logger trước init để thấy log lúc init. Bản release: enabled = false hoặc minLevel = WARN.
+    Ads.logger.init(LogConfig(enabled = BuildConfig.DEBUG, minLevel = LogLevel.FLOW), debug = BuildConfig.DEBUG)
+
+    // 2. Init: chọn MỘT trong ba cách ở mục 2.
+    Ads.init(this, "<config>.json", isDebug = BuildConfig.DEBUG)
+
+    // 3. Tracking (tuỳ chọn, theo yêu cầu của app): module `super-ads-tracking` (chỉ cần thêm dependency, tự cài; bật/tắt bằng `global.tracking.*`), ...
+    // 4. App Open (nếu có): AppLifecycleMonitor(...).register()  — xem super-ads-add-placement
+}
+```

package/skills/super-ads-integrate/templates/gradle-dependencies.md

@@ -0,0 +1,17 @@
+# Mẫu khai dependency (GMS cổ điển)
+
+> Mẫu: thêm vào app thật chỉ khi user đã đồng ý (thêm dependency). Giải thích từng artifact, version, repo Maven: [../references/gradle-setup.md](../references/gradle-setup.md).
+
+```gradle
+def superAds = '4.0.0'
+implementation "com.android.fullhd.ads:SuperAds:$superAds"
+// bộ nền (mục 1b): luôn khai
+implementation "com.android.fullhd.ads:SuperAdsInHouse:$superAds"
+implementation "com.android.fullhd.ads:SuperAdsDebug:$superAds"
+debugImplementation "com.android.fullhd.ads:SuperAdsDebugOverride:$superAds"
+// plugin network theo config
+implementation "com.android.fullhd.ads:SuperAdsAdmob:$superAds"
+// plugin khác: cùng $superAds
+implementation "com.android.fullhd.ads:SuperAdsTracking:$superAds"   // chỉ khi app cần tracking Firebase (user đã chọn)
+implementation 'com.android.fullhd.layout:SuperAdsLayout:<version>'
+```