@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/skills/adspro-to-superads/references/user-questions.md

@@ -0,0 +1,53 @@
+# Câu hỏi phải hỏi user (Nhóm A-D)
+
+Mỗi câu hỏi phải có **phương án khuyến nghị** và nêu **hệ quả**. Agent không được tự chọn thay
+user ở nhóm A và B. Gộp câu hỏi cùng nhóm vào **một** lần hỏi.
+
+- Nhóm B: hỏi khi lập inventory Phase 0.
+- Nhóm A và D: hỏi **trước** Phase 3.
+- Nhóm C: hỏi **một lần** đầu Phase 4.
+
+Mọi câu trả lời ghi vào mục "Decisions" trong `migration-inventory.md`.
+
+## Nhóm A — tính năng không chuyển được (loại C)
+
+| Tình huống | Câu hỏi | Phương án gợi ý |
+|---|---|---|
+| App dùng `AdmobNativePip` | SuperAds không có native PIP. Xử lý placement này thế nào? | (1) Bỏ PIP, chuyển thành `NATIVE` thường ở cùng vị trí — khuyến nghị; (2) Giữ AdsPro riêng cho PIP — không khuyến nghị, hai SDK cùng tồn tại; (3) Tạm tắt placement |
+| App dùng `AdmobNativeCollapsibleHalfSize` | Không có half-size. Dùng gì thay? | (1) `NATIVE_COLLAPSIBLE` với layout expanded nhỏ hơn — khuyến nghị; (2) Bỏ, dùng `NATIVE` |
+| Space có `adsType` không nằm trong bảng map | `adsType` này không có format tương ứng. Ý định sản phẩm là gì? | Liệt kê 2–3 format gần nhất kèm khác biệt hành vi |
+
+## Nhóm B — behavior không suy ra được từ code
+
+| Tình huống | Câu hỏi | Phương án gợi ý |
+|---|---|---|
+| Code cũ nav ở cả hai callback, hoặc nav ngoài callback | Placement này nav khi ad *hiện* hay khi ad *đóng*? | Mặc định SDK là `NAVIGATE_ON_DISMISS`; nêu hệ quả UX từng lựa chọn |
+| `load()` gọi trong `onCreate` của Activity, không thuộc màn nào | Preload này nên gắn với event màn nào? | Đề xuất màn gần nhất trong flow + phương án preload ngay sau init |
+| Không rõ preload áp cho phiên nào | Preload cho người mở lần đầu, người quay lại, hay cả hai? | Khuyến nghị **cả hai** (`_fo` + `_fn`) nếu code cũ preload vô điều kiện |
+| Reload cũ vừa có timer vừa có click | Giữ cả `reload.auto` và `reload.click`, hay chỉ một? | Chain chỉ nhận click |
+| Space trong JSON nhưng zero call site (vd `Banner_chung`) | Giữ placement này hay bỏ? | (1) Giữ, ghi vào Documented exclusions — khuyến nghị (an toàn cho RC); (2) Bỏ khỏi config |
+| Hai space khác nhau nhưng cùng ý nghĩa | Gộp hay giữ tách? | Khuyến nghị **giữ tách** để bảo toàn analytics |
+| Event cũ mang `previous_screen`/`next_screen` trong bundle | Event khai trong JSON không mang được cặp screen. Bỏ cặp screen, hay giữ tracking app-side? | (1) Bỏ, dùng `adItemId` — khuyến nghị; (2) Collect `TrackerEvent.Impression` rồi tự ghép screen từ state app |
+| Tên event analytics cũ rải rác trong Kotlin | Tên nào đưa vào `tracking.event*`, tên nào giữ app-side? | Event AB/theo placement vào JSON; event bespoke cần ngữ cảnh app thì giữ trên flow |
+
+## Nhóm C — quyết định kiến trúc (đầu Phase 4)
+
+| Câu hỏi | Phương án gợi ý |
+|---|---|
+| Nhà cho wrapper: moi ruột `AdsUtils.kt` cũ, hay tạo `AdsSP.kt` mới? | (1) Moi ruột file cũ — **khuyến nghị**, giữ path nên ~40 màn không đổi import; (2) File mới kiểu SlideShow — sạch tên nhưng phải sửa import ở mọi màn |
+| Nhà cho `EventScreen`: thêm vào file base có sẵn hay tạo file mới? | (1) Thêm vào file base sẵn có; (2) File mới `EventScreen.kt` nếu package base không có nhà hợp lý |
+| Có dọn tham số inert trong migration không? | Khuyến nghị **không** — tách commit riêng sau khi verify xong |
+| Config: một file JSON asset, hay thêm nhánh Remote Config ngay? | Khuyến nghị asset trước, RC sau khi verify |
+
+## Nhóm D — hạ tầng (hỏi ngay khi phát hiện)
+
+| Tình huống | Câu hỏi |
+|---|---|
+| Config có network nhưng thiếu module | Config có `"network": "CloudX"` nhưng chưa có `SuperAdsCloudX`. Thêm module hay bỏ network khỏi config? |
+| Thiếu `io.cloudx.APP_KEY` / `applovin.sdk.key` | Cung cấp key, hay bỏ network đó? |
+| App chưa có `screenName()` / registry tracking | Không có gì dựng chuỗi event preload. Wire tracking screen trước, hay preload theo cách khác? |
+| App có RC key timing ads (tên tuỳ app, vd `keyTimeBetweenAdInter`) | JSON chỉ có `show.timeBetweenMs` cố định. Ops còn chỉnh nóng qua RC không? |
+| Có native-sau-inter | Production: mấy native/lần inter? RC/AB nào (nếu có) tắt native phụ? Counter `% N` ra pos nào? Điền JSON theo đo, không theo template |
+| Click reload cùng space, khác layout | Tách twin SuperAds theo Bảng D, chung unit nếu AdsPro chung `ids[]` |
+| `minimumFetchIntervalInSeconds` | SlideShow đặt `0` (fetch mọi lần). Giữ `0` hay đặt giá trị an toàn hơn cho production? |
+| App đã có AppsFlyer / Adjust / Meta | Giữ nguyên kênh nào? `SuperAdsTracking` là **mặc định nên có** (Phase 1) — thiếu nó là mất `ad_impression` / `ad_click` Firebase (`MIGRATION.md:452`). Chỉ bỏ khi app tự bắn doanh thu Firebase ở chỗ khác và user xác nhận |

package/skills/adspro-to-superads/snippets/ads-api-quick.md

@@ -0,0 +1,20 @@
+# Ads API — tra nhanh
+
+```kotlin
+// Init
+Ads.init(application, configProvider = { getConfig(...) }, isDebug = isDebug)
+Ads.isPremium = purchased
+// Consent TRƯỚC preload/show/app open (core không tự chặn): Activity đầu
+Ads.gdpr.requestAndShowIfRequired(activity, isDebug, timeoutMs = /* timeout AdsPro của app */) { onConsentDone(); next() }
+
+// Inline (native / banner)
+Ads.show(placementId, activity, AdTarget.AdView(container, lifecycle), callback)
+
+// Fullscreen / reward
+Ads.show(placementId, activity, callback = NavAdCallback { ... })
+Ads.show(placementId, activity, callback = RewardAdCallback(true) { ... })
+
+// Preload — KHÔNG gọi thủ công. EventScreen + preload.eventActive.
+Ads.dispatchEvent(activity, "create_open_screen_5_fo")
+```
+```

package/skills/adspro-to-superads/templates/migration-inventory.md

@@ -0,0 +1,42 @@
+# migration-inventory.md — mẫu Bảng A-D
+
+## Bảng A — placement identity + behavior
+
+| spaceName | adsType | ids[] | layout collapsed | layout expanded | show API cũ | nav từ callback nào | reload trigger cũ | space reload cũ | RC key | placement | format | mode.show | mode.navigate | status |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Native_Home | native | 1 | native_collap_small | - | show | - | click | Native_Reload | config_ads_22_4 | Native_Home | NATIVE | LOAD_AND_SHOW | - | TODO |
+| Interstitial_Chung | interstitial | 1 | - | - | show + gate LOADED | onAdDismissed | - | - | config_ads_22_4 | Interstitial_Chung | INTER | SHOW_LOADED | NAVIGATE_ON_DISMISS | TODO |
+
+Cột `placement` = nguyên văn `spaceName`. **MUST NOT CHANGE.**
+
+## Bảng B — preload moment (một hàng mỗi call site `load()`)
+
+| File:line | space | màn đang đứng | screenName() | thời điểm | chuỗi event | status |
+|---|---|---|---|---|---|---|
+| LanguageFragment.kt:45 | Native_Onboarding | Language | open_screen_1 | onViewReady | create_open_screen_1_fo | TODO |
+
+Không gom nhiều `load()` của cùng space thành một hàng. Mỗi thời điểm là một hàng.
+
+## Bảng C — cặp reload
+
+| placement nguồn | trigger | placement đích | chu kỳ (ms) | key JSON | status |
+|---|---|---|---|---|---|
+| Native_Home | click | Native_Reload | - | reload.click.placementID | TODO |
+| Native_Record_Video | auto | Native_Record_Video_ReLoad_15s | 15000 | reload.auto.placementID + show.timeAutoReloadMs | TODO |
+
+## Bảng D — click reload theo layout (khi app có click reload)
+
+Bảng C gom trigger. Bảng D vì SDK bind layout trên **adItem đích**. Hàng mẫu chỉ hiểu cột —
+điền space/layout/unit **của app này**. Tách twin **chỉ khi** layout hoặc unit lúc click khác nhau.
+
+| nguồn | layout lúc show | unit AdsPro lúc click | SuperAds reload placement | unit | layout đích | self-click? |
+|---|---|---|---|---|---|---|
+| *(space)* | *(xml)* | *(ids click)* | *(space reload cũ hoặc twin mới)* | *(khớp AdsPro)* | *(= layout show)* | *(click lại cùng space?)* |
+
+Space reload **zero call site** → Exclusions, không làm đích vì tên.
+
+## Các mục khác trong cùng file
+
+- **Decisions** — câu trả lời nhóm A/B/C/D.
+- **Inert parameters** — tham số giữ chữ ký nhưng không còn tác dụng.
+- **Documented exclusions** — space được giữ / bỏ có lý do (vd `Banner_chung` zero call site).

package/skills/super-ads-ab-test/SKILL.md

@@ -1,33 +1,50 @@
 ---
 schema: 1
 name: super-ads-ab-test
-description: Use when the user wants a Firebase A/B test of SuperAds config — confirm the hypothesis, generate the two variant JSON files with make_ab_variants, and hand the user exact Firebase Console instructions (parameter, activation event, tracking); the agent never touches Firebase or app code.
-version: 1.0.0
+description: Use when the user wants a Firebase A/B test of SuperAds config, generating two variant JSON files and handoff steps
+version: 1.1.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Tạo A/B test config SuperAds cho Firebase
 
 Agent làm đúng 3 việc: **chốt A/B là gì với user** → **sinh 2 file config** → **bàn giao hướng dẫn Firebase**. Agent **không** thao tác Firebase Console, **không** sửa code app, **không** sửa asset hay working config.
 
-| Cần | Tài liệu |
-|---|---|
-| Mẫu tin nhắn bàn giao Firebase (bắt buộc dùng) | [references/firebase-handoff-template.md](references/firebase-handoff-template.md) |
-| Hợp đồng SDK (activation, `ab_variant`, provenance) | `MIGRATION.md`, mục "A/B test bằng remote config" |
-| Đối soát sau khi chạy (BigQuery, quy tắc lọc) | [../super-ads-release-check/references/firebase-ab-checklist.md](../super-ads-release-check/references/firebase-ab-checklist.md) |
-| Tool sinh variant | `make_ab_variants` (`tools/ai_agent_tools/src/mcp/tools.js:254-278`): generate-only, tự chặn variant lệch ngoài path được đổi, trả `validationA` / `validationB` |
-| Overload nạp JSON có cờ activated | `SA/api/Ads.kt:197` |
-| Luật tên event | `super-ads-tracking/src/main/java/com/android/fullhd/super_ads/tracking/gateway/FirebaseEventName.kt:33-40` |
-
 ## When to use
 - "Làm A/B test cooldown inter 30s vs 60s", "test bật/tắt native ở màn X", "chia 2 nhóm config qua Firebase".
 
-## When NOT to use
+## 🚫 When NOT to use
 - Chỉ đổi một giá trị config cho mọi user → `super-ads-config`.
 - Chạy app với config khác asset để test cục bộ → `super-ads-debug-override`.
 - Đọc kết quả / đối soát experiment đã chạy → `super-ads-release-check` (checklist Firebase A/B).
 
-## Quy trình
+## 📋 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.
+- MCP `super-ads` đã kết nối (`read_working_config`, `make_ab_variants`).
+- App đã có đường nạp Remote Config có cờ activated (kiểm ở Workflow bước 1). Hợp đồng SDK (activation, `ab_variant`, provenance): `MIGRATION.md`, mục "A/B test bằng remote config".
+
+## ⚡ Quick Reference
+
+| Cần | Tài liệu |
+|---|---|
+| Mẫu tin nhắn bàn giao Firebase (bắt buộc dùng) | [templates/firebase-handoff-template.md](templates/firebase-handoff-template.md) |
+| Đối soát sau khi chạy (BigQuery, quy tắc lọc) | [../super-ads-release-check/references/firebase-ab-checklist.md](../super-ads-release-check/references/firebase-ab-checklist.md) |
+
+Skill này không có `references/`, `snippets/`, `examples/` hay `scripts/` riêng.
+
+## 🏗️ Recommended Architecture
+Hai file variant chỉ khác nhau ở các path đã chốt và `global.version`. Cả hai mang **cùng** activation event để Firebase đếm user ở cả hai nhóm; `ab_variant` (`<exp>_A` / `<exp>_B`) dùng khi phân tích.
+
+## Workflow
+
+### Stop conditions
+- App không có `loadFromJson(json, firebaseActivated = true)` đọc từ Remote Config (bước 1).
+- User chưa xác nhận bảng A/B (bước 2).
+- Working config không phải asset app đang nạp.
+- Version trùng, tên event sai luật hoặc trùng exposure.
+- `make_ab_variants` báo invariant / validation lỗi, hoặc `diffAB` lệch bảng đã chốt.
 
 ### 1. Kiểm app có đường nạp Remote Config đúng (điểm dừng)
 Tìm trong code app lời gọi `Ads.loadFromJson(json, firebaseActivated = true)` và **tên tham số Remote Config** mà chỗ đó đọc (app mẫu: `ads_config_v2` trong `app/src/main/java/com/android/hd/ads2026/RemoteConfigAbLoader.kt`). Đồng thời xác nhận giá trị chỉ được nạp khi đến từ remote sau `fetchAndActivate()`.
@@ -67,25 +84,76 @@ Rồi trình **bảng xác nhận** và chờ user trả lời "đúng" (hoặc
 7. Đối chiếu `diffAB` với bảng đã chốt: hai file chỉ được khác nhau ở các path trong bảng + `global.version`. Khác thêm ⇒ dừng, báo user.
 
 ### 4. Bàn giao Firebase
-Điền [references/firebase-handoff-template.md](references/firebase-handoff-template.md) và gửi user, đủ mọi mục. Kết thúc ở đây: user tự cấu hình Firebase.
+Điền [templates/firebase-handoff-template.md](templates/firebase-handoff-template.md) và gửi user, đủ mọi mục. Kết thúc ở đây: user tự cấu hình Firebase.
 
-## Contract
-**MUST**
+## 🔧 API Reference
+
+| Mục | Mô tả | Nguồn |
+|---|---|---|
+| `make_ab_variants` | Generate-only, tự chặn variant lệch ngoài path được đổi, trả `validationA` / `validationB` | `tools/ai_agent_tools/src/mcp/tools.js:254-278` |
+| Overload nạp JSON có cờ activated | `Ads.loadFromJson(json, firebaseActivated = true)` | `SA/api/Ads.kt:197` |
+| Luật tên event | Giới hạn tên activation / exposure | `super-ads-tracking/src/main/java/com/android/fullhd/super_ads/tracking/gateway/FirebaseEventName.kt:33-40` |
+
+## ✅ Best Practices
 - Điểm dừng ở bước 1 và bước 2; không có xác nhận "đúng" của user thì không sinh file.
 - `global.version` của A và B khác nhau, ổn định, không trùng version asset.
 - Activation event **cùng tên** ở A và B; mỗi experiment một tên riêng.
 - Nói rõ cho user: tên tham số Remote Config, file nào vào Baseline / Variant, tên activation event, goal, các event và param tracking.
 
-**MUST NOT**
+## ❌ Anti-patterns
 - Không thao tác Firebase Console, không gọi API Firebase.
 - Không sửa code app, asset hay working config: không `apply_patch`, `replace_working_config`, `sync_to_source`.
 - Không tự chọn giá trị thử nghiệm, % user hay tên experiment thay user.
 - Không khai `activation_event` vào asset.
 - Không đặt tên activation trùng tên exposure hay tên reserved.
 
-## Stop conditions
-- App không có `loadFromJson(json, firebaseActivated = true)` đọc từ Remote Config (bước 1).
-- User chưa xác nhận bảng A/B (bước 2).
-- Working config không phải asset app đang nạp.
-- Version trùng, tên event sai luật hoặc trùng exposure.
-- `make_ab_variants` báo invariant / validation lỗi, hoặc `diffAB` lệch bảng đã chốt.
+## ⚠️ Common Issues
+
+| Problem | Cause | Solution |
+|---|---|---|
+| Firebase không đếm được user | App gọi `loadFromJson(json)` không cờ activated nên activation event không bắn | Dừng ở bước 1, trỏ user tới `MIGRATION.md`, không tự viết code app |
+| `make_ab_variants` báo invariant / validation lỗi | Variant lệch ngoài path được đổi hoặc config không hợp lệ | Dừng, báo user, không ghi file |
+
+## Files created
+Hai file variant (JSON) trong gốc repo của app, do agent ghi sau khi user xác nhận bảng A/B:
+- `super-ads-ab-test/<exp>/variant_A.json`
+- `super-ads-ab-test/<exp>/variant_B.json`
+
+## Files modified
+Chỉ `.gitignore` ở gốc repo (thêm dòng `/super-ads-ab-test/` nếu chưa có). Không sửa code app, asset hay working config.
+
+## Verification
+- `invariantsA` / `invariantsB` không có vi phạm; `validationA` / `validationB` không có error.
+- `diffAB` chỉ khác nhau ở các path trong bảng đã chốt + `global.version`.
+- `<exp>_A` ≠ `<exp>_B`, cả hai ≠ `global.version` hiện tại; tên activation hợp lệ và không trùng exposure.
+
+## Checklist
+- [ ] App có đường nạp `loadFromJson(json, firebaseActivated = true)` từ Remote Config.
+- [ ] User xác nhận bảng A/B.
+- [ ] Working config đúng là asset app đang nạp.
+- [ ] Hai file variant sinh xong, `diffAB` khớp bảng.
+- [ ] `.gitignore` có `/super-ads-ab-test/`.
+- [ ] Đã gửi bản bàn giao Firebase đủ mọi mục.
+
+## 📈 Performance Notes
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+> **Not applicable for this skill.**
+
+## Output
+Đường dẫn hai file variant, bảng A/B đã chốt, và bản bàn giao Firebase đã điền từ template (tham số Remote Config, file Baseline / Variant, activation event, goal, event và param tracking).
+
+## Examples
+- [templates/firebase-handoff-template.md](templates/firebase-handoff-template.md): mẫu bàn giao đã có đủ mục để điền.
+
+## 📚 References
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-upgrade](../super-ads-upgrade/SKILL.md)
+- [super-ads-config](../super-ads-config/SKILL.md), [super-ads-debug-override](../super-ads-debug-override/SKILL.md), [super-ads-release-check](../super-ads-release-check/SKILL.md)
+- `MIGRATION.md`, mục "A/B test bằng remote config"
+
+## 🏷️ Tags
+`super-ads` `ab-test` `firebase` `remote-config` `variants` `experiment`

package/skills/super-ads-adb-test/SKILL.md

@@ -1,54 +1,53 @@
 ---
 schema: 1
 name: super-ads-adb-test
-description: Use when you need to verify SuperAds behaviour on a real Android device or emulator without changing the app — build, install, drive the UI, capture logcat and check each scenario step against log/UI expectations.
-version: 1.0.0
+description: Use when verifying SuperAds behaviour on a device or emulator by running do/expect scenarios without editing the app
+version: 1.1.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Test SuperAds trên thiết bị (không sửa app)
 
 Chạy kịch bản `do` / `expect` trên thiết bị: build + cài app, điều khiển UI, thu Logcat, so từng bước với kỳ vọng, báo `PASS` / `FAIL` / `SKIP` / `UNKNOWN` kèm bằng chứng.
 
-| Bước | Tài liệu |
-|---|---|
-| Định dạng kịch bản | [references/scenario-format.md](references/scenario-format.md) |
-| Kịch bản mẫu | [references/scenarios-sample.md](references/scenarios-sample.md) |
-| Regex log theo sự kiện | [references/log-assertions.md](references/log-assertions.md) |
-| App mẫu trong repo (ví dụ) | [references/sample-app-notes.md](references/sample-app-notes.md) |
-| Bật log SDK | [../super-ads-debug/references/logging-setup.md](../super-ads-debug/references/logging-setup.md) |
-
 ## When to use
 - Kiểm một placement mới gắn, một thay đổi config, hoặc tái hiện lỗi trên máy thật.
 - Chạy lặp lại cùng một kịch bản trước/sau khi sửa (dùng cho `super-ads-debug`, `super-ads-show-rate`, `super-ads-add-placement`).
 
-## When NOT to use
+## 🚫 When NOT to use
 - Kiểm logic SDK không cần máy: bộ JVM/Robolectric `ScenarioRunner` (`./gradlew superAdsLogicVerification`, `super-ads-test/README-scenarios.md:9-20`).
 - Instrumentation với ad thật cho SDK: `scripts/verify-all.sh`, `super-ads-test/README-real-ads-instrumentation.md`.
-- Tìm nguyên nhân một lỗi: `super-ads-debug` (skill này chỉ chạy và báo kết quả).
+- Tìm nguyên nhân một lỗi: [super-ads-debug](../super-ads-debug/SKILL.md) (skill này chỉ chạy và báo kết quả).
+
+## 📋 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.
+- Có thiết bị: `adb devices` có ít nhất một máy ở trạng thái `device`. Nhiều máy thì chỉ định serial (`adb -s <serial>`), như `scripts/verify-all.sh:21-22`.
+- Coi applicationId, Activity khởi động, tag log, màn hình là **tham số**. Đọc từ `build.gradle`, `AndroidManifest.xml`, code `Application` của app đang test.
+- Biết config đang nạp (lời gọi `Ads.init` trong `Application`); chỉ dùng placement có thật trong đó.
+- Log SDK đã bật ở bản đang cài (cách bật: [logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 2).
+
+## ⚡ Quick Reference
+| Cần | Mở |
+|---|---|
+| Định dạng kịch bản (`do` / `expect`, quy tắc) | [references/scenario-format.md](references/scenario-format.md) |
+| Kịch bản mẫu S1-S6 | [examples/scenarios-sample.md](examples/scenarios-sample.md) |
+| Regex log theo sự kiện (thành công, blocked, error) | [references/log-assertions.md](references/log-assertions.md) |
+| App mẫu trong repo (ví dụ) | [references/sample-app-notes.md](references/sample-app-notes.md) |
+| Bật log SDK, file `.logads` | [../super-ads-debug/references/logging-setup.md](../super-ads-debug/references/logging-setup.md) |
 
-## Authority order
+Trạng thái kết quả: `PASS` / `FAIL` / `SKIP (lý do)` / `UNKNOWN (lý do)`.
+
+## 🏗️ Recommended Architecture
+Thứ tự nguồn sự thật:
 1. Code SDK (chuỗi log, mã lỗi) và code app đang test (màn hình, id, tag log).
 2. Config đang được app nạp.
 3. Tài liệu skill. Nhãn nút, id view trong tài liệu là của app mẫu.
 
-## Contract
-**MUST**
-- Coi applicationId, Activity khởi động, tag log, màn hình là **tham số**. Đọc từ `build.gradle`, `AndroidManifest.xml`, code `Application` của app đang test.
-- Đọc config đang nạp trước (lời gọi `Ads.init` trong `Application`), chỉ dùng placement có thật trong đó.
-- Mỗi kịch bản: bắt đầu từ trạng thái log sạch (`adb logcat -c`, hoặc đánh dấu thời điểm để lấy file `.logads` mới) → `launch` → các bước → lưu file log riêng. Nguồn log ưu tiên là file `.logads`, Logcat là dự phòng ([logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 6).
-- Mỗi kết luận `PASS` / `FAIL` trích dòng log hoặc trạng thái UI làm bằng chứng.
-- Trả lại trạng thái máy đã đổi (mạng, xoay màn) kể cả khi kịch bản fail.
-- Có nhiều máy thì chỉ định serial (`adb -s <serial>`), như `scripts/verify-all.sh:21-22`.
-
-**MUST NOT**
-- Không sửa code, manifest, Gradle, asset config của app. Kể cả "tạm thời".
-- Không ghi đè file config của app bằng working config `tmp-*.json` của MCP.
-- Không bấm vào ad thật (click) trên bản production, và không chạy với unit thật khi chưa được user đồng ý (rủi ro invalid traffic).
-- Không báo `PASS` cho kỳ vọng `never` khi không có bằng chứng dương rằng lời gọi đã tới SDK ([log-assertions.md](references/log-assertions.md) mục 4).
-- Không chạy `network off` trên emulator/LDPlayer: mất luôn kết nối adb.
+## Workflow
 
-## Stop conditions (dừng và hỏi user)
+### Dừng và hỏi user khi
 - `adb devices` không có máy nào ở trạng thái `device`.
 - Logcat không có dòng `SuperAdsSDK` sau `launch`: logger chưa bật ở bản đang cài. Muốn bật thì phải sửa app, nên hỏi user (cách bật: [logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 2).
 - Kịch bản cần config khác với config app đang nạp. App có hook override (bản debug có `ConfigOverrideReceiver`) ⇒ dùng `super-ads-debug-override`, không phải sửa app. Không có hook ⇒ đưa user lựa chọn:
@@ -58,7 +57,7 @@ Chạy kịch bản `do` / `expect` trên thiết bị: build + cài app, điề
 - Config dùng unit thật và kịch bản có click hoặc show nhiều lần.
 - Build lỗi. Báo nguyên văn lỗi, không tự sửa Gradle.
 
-## Phase 1: Chuẩn bị
+### Phase 1: Chuẩn bị
 1. `adb devices -l`. Chọn serial; ghi model và loại (máy thật hay emulator).
 2. Lấy tham số app: `applicationId` (`build.gradle`), Activity LAUNCHER (`AndroidManifest.xml`), tag log của app (`Application`), file config đang nạp.
 3. Build và cài bản debug: `./gradlew :<appModule>:assembleDebug`, rồi `adb -s <serial> install -r <apk>`. Ghi `versionName`.
@@ -68,7 +67,7 @@ Chạy kịch bản `do` / `expect` trên thiết bị: build + cài app, điề
 
 **Verify:** app đã cài (`adb shell pm path <pkg>` trả đường dẫn), có công cụ điều khiển UI.
 
-## Phase 2: Kiểm điều kiện quan sát
+### Phase 2: Kiểm điều kiện quan sát
 1. Chọn nguồn log. **File `.logads`** (khi app debuggable và `isDebug = true` hoặc đã bật ghi file): ghi lại thời điểm bắt đầu, sau kịch bản lấy file mới nhất bằng `adb -s <serial> exec-out run-as <pkg> cat cache/logads/<file>.logads > <scenario>.logads`; mỗi kịch bản một file (app phải chạy lại để có file mới, hoặc cắt theo giờ). **Logcat** (dự phòng): `adb logcat -c`, rồi ghi log nền `adb -s <serial> logcat -v time -s SuperAdsSDK:V <AppTag>:V > <scenario>.log`.
 2. `launch` app, chờ 5–10s.
 3. Có dòng `SuperAdsSDK` không? Không có thì Stop.
@@ -76,26 +75,56 @@ Chạy kịch bản `do` / `expect` trên thiết bị: build + cài app, điề
 
 **Verify:** file log có dòng của SDK sau khi launch.
 
-## Phase 3: Chạy kịch bản
-- Lấy kịch bản từ [scenarios-sample.md](references/scenarios-sample.md), hoặc viết mới theo [scenario-format.md](references/scenario-format.md).
+### Phase 3: Chạy kịch bản
+- Lấy kịch bản từ [scenarios-sample.md](examples/scenarios-sample.md), hoặc viết mới theo [scenario-format.md](references/scenario-format.md).
 - Với mỗi kịch bản: kiểm `needs` với config đang nạp. Không đạt thì `SKIP` kèm lý do.
 - Thực hiện từng `do`. Sau mỗi `expect`, grep file log hoặc đọc cây UI. Kỳ vọng đầu tiên fail thì dừng kịch bản đó, giữ log, chạy bước trả lại trạng thái.
 
 **Verify:** mỗi kịch bản có kết quả và file log riêng.
 
-## Phase 4: Báo cáo
+### Phase 4: Báo cáo
 Bảng `kịch bản | kết quả | bằng chứng | ghi chú`. Kèm serial, model, `versionName`, config đang nạp (`global.version`), đường dẫn các file log.
-`FAIL` thì chuyển sang `super-ads-debug` với file log làm đầu vào.
+`FAIL` thì chuyển sang [super-ads-debug](../super-ads-debug/SKILL.md) với file log làm đầu vào.
 
 **Verify:** không có dòng `PASS` nào thiếu bằng chứng.
 
-## Anti-patterns
+## 🔧 API Reference
+Bước `do` (`launch`, `tap`, `select`, `wait`, `back`, `home`/`resume`, `rotate`, `network`) và `expect` (`log`, `logCount`, `never`, `ui`): [references/scenario-format.md](references/scenario-format.md). Regex theo sự kiện: [references/log-assertions.md](references/log-assertions.md).
+
+## ✅ Best Practices
+- Mỗi kịch bản: bắt đầu từ trạng thái log sạch (`adb logcat -c`, hoặc đánh dấu thời điểm để lấy file `.logads` mới) → `launch` → các bước → lưu file log riêng. Nguồn log ưu tiên là file `.logads`, Logcat là dự phòng ([logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 6).
+- Mỗi kết luận `PASS` / `FAIL` trích dòng log hoặc trạng thái UI làm bằng chứng.
+- Trả lại trạng thái máy đã đổi (mạng, xoay màn) kể cả khi kịch bản fail.
+- Chờ theo dòng log (`expect … within`) thay vì ngủ cố định.
+
+## ❌ Anti-patterns
+- Sửa code, manifest, Gradle, asset config của app. Kể cả "tạm thời".
+- Ghi đè file config của app bằng working config `tmp-*.json` của MCP.
+- Bấm vào ad thật (click) trên bản production, hoặc chạy với unit thật khi chưa được user đồng ý (rủi ro invalid traffic).
+- Báo `PASS` cho kỳ vọng `never` khi không có bằng chứng dương rằng lời gọi đã tới SDK ([log-assertions.md](references/log-assertions.md) mục 4).
+- Chạy `network off` trên emulator/LDPlayer: mất luôn kết nối adb.
 - Dùng `sleep` cố định thay cho chờ dòng log.
 - Grep tag Logcat theo `name` (`AdSFl`, `RuleMg`…). Tag luôn là `SuperAdsSDK`, `name` nằm trong message.
 - Mở màn test bằng `am start` khi Activity không exported.
 - Bấm nút `Dismiss` của màn test để kiểm dismiss-reload (nút đó gọi `Ads.dismissByPlacement`, không kích reload).
 - Khớp theo tên lỗi hay tên rule. Dùng `code = N` (tên rule trên bản R8 có thể đã bị đổi).
 
+## ⚠️ Common Issues
+**Không có dòng `SuperAdsSDK` sau `launch`.**
+Cause: logger chưa bật ở bản đang cài. Solution: dừng và hỏi user; bật logger là sửa app ([logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 2).
+
+**Kịch bản cần config khác với config đang nạp.**
+Cause: config app không thỏa `needs`. Solution: `super-ads-debug-override` nếu có hook; không thì đưa user ba lựa chọn ở "Dừng và hỏi user khi".
+
+## Files created
+Skill này không tạo file nào trong app; nó chỉ ghi file log mỗi kịch bản (`<scenario>.logads` hoặc `<scenario>.log`) ngoài source.
+
+## Files modified
+Skill này không sửa file nào của app. Chỉ khi user chọn phương án sửa config để chạy kịch bản thì mới có thay đổi (đó là sửa app, cần duyệt).
+
+## Verification
+Mỗi phase có dòng **Verify** riêng ở Workflow. Kết thúc: không có dòng `PASS` nào thiếu bằng chứng, và `git status` của app sạch như trước khi chạy.
+
 ## Checklist
 - [ ] Đã chọn serial, đã cài đúng bản, có `versionName`.
 - [ ] Logcat có log SDK.
@@ -103,5 +132,25 @@ Bảng `kịch bản | kết quả | bằng chứng | ghi chú`. Kèm serial, mo
 - [ ] Trạng thái máy đã được trả lại.
 - [ ] Không file nào của app bị sửa (`git status` của app sạch như trước khi 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ảng kết quả theo kịch bản, thông tin thiết bị/bản build/config, đường dẫn log, các kịch bản `SKIP` / `UNKNOWN` kèm lý do, và việc cần làm tiếp (vd chuyển `super-ads-debug`).
+
+## Examples
+Kịch bản hoàn chỉnh S1-S6 (cooldown 101, native inline, collapsible dismiss-reload, App Open guard 108, premium 103, mất mạng 104): [examples/scenarios-sample.md](examples/scenarios-sample.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-show-rate](../super-ads-show-rate/SKILL.md), [super-ads-debug-override](../super-ads-debug-override/SKILL.md)
+- [Bật log SDK](../super-ads-debug/references/logging-setup.md)
+
+## 🏷️ Tags
+`superads` `adb` `device-test` `scenario` `logcat` `do-expect`

package/skills/super-ads-adb-test/{references → examples}/scenarios-sample.md

@@ -1,14 +1,14 @@
 # Bộ kịch bản mẫu
 
-> Định dạng: [scenario-format.md](scenario-format.md). Regex: [log-assertions.md](log-assertions.md).
-> `<P>` là placement **lấy từ config đang được nạp**, không phải tên cố định. Nhãn nút theo app mẫu ([sample-app-notes.md](sample-app-notes.md)); app khác thì thay bằng màn tương đương.
+> Định dạng: [scenario-format.md](../references/scenario-format.md). Regex: [log-assertions.md](../references/log-assertions.md).
+> `<P>` là placement **lấy từ config đang được nạp**, không phải tên cố định. Nhãn nút theo app mẫu ([sample-app-notes.md](../references/sample-app-notes.md)); app khác thì thay bằng màn tương đương.
 > `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
 
 Mỗi kịch bản ghi `needs` (điều kiện config). Đọc config trước khi chạy: điều kiện sai thì **bỏ qua kịch bản và ghi lý do**, không chỉnh config cho vừa.
 
 ## S1. Inter show rồi bị chặn bởi cooldown (101)
 - needs: `<P>` fullscreen, `show.timeBetweenMs` của adItem đầu > thời gian thao tác (vd ≥ 10000), mạng bật, không premium.
-- App mẫu: `<P>` = `InterChain` (adItem `chain_inter`, `show.timeBetweenMs = 15000`), mở qua Playground. Màn `Interstitial` (`test_inter`) không có cooldown nên kịch bản sẽ `SKIP` ở đó ([sample-app-notes.md](sample-app-notes.md)).
+- App mẫu: `<P>` = `InterChain` (adItem `chain_inter`, `show.timeBetweenMs = 15000`), mở qua Playground. Màn `Interstitial` (`test_inter`) không có cooldown nên kịch bản sẽ `SKIP` ở đó ([sample-app-notes.md](../references/sample-app-notes.md)).
 - steps:
   1. `launch` → `tap text:"🎮 Playground (chọn placement)"` → `select id:spinnerCategory value:"INTERSTITIAL_NATIVE_CHAIN"` → `select id:spinnerPlacement value:"<P>"` → `tap id:btnShow`
   2. `expect log '\[AdSFl\] info=adEventSink Impression: public=<P> ' within 30s`
@@ -23,7 +23,7 @@ Mỗi kịch bản ghi `needs` (điều kiện config). Đọc config trước k
 
 ## S3. Collapsible: người dùng bấm đóng → dismiss-reload
 - needs: `<P>` collapsible có `reload.dismiss.placementID`.
-- App mẫu: `<P>` = `native_collapsible_dismiss_reload` hoặc `test_native_collapsible_reload_dismiss`, mở qua Playground (`select id:spinnerCategory value:"NATIVE_COLLAPSIBLE"` → `select id:spinnerPlacement value:"<P>"`). Màn `Native Collapsible` (`test_native_collapsible`) không có `reload.*` ([sample-app-notes.md](sample-app-notes.md)).
+- App mẫu: `<P>` = `native_collapsible_dismiss_reload` hoặc `test_native_collapsible_reload_dismiss`, mở qua Playground (`select id:spinnerCategory value:"NATIVE_COLLAPSIBLE"` → `select id:spinnerPlacement value:"<P>"`). Màn `Native Collapsible` (`test_native_collapsible`) không có `reload.*` ([sample-app-notes.md](../references/sample-app-notes.md)).
 - steps: `launch` → mở Playground, chọn `<P>` như trên → `tap id:btnShow` → chờ Impression → bấm **nút đóng của chính ad** (không phải nút `Dismiss` của màn test, nút đó gọi `Ads.dismissByPlacement`, `app/src/main/java/com/android/hd/ads2026/test/BaseTestActivity.kt:107-110`) → `expect log '\[ReloadCoord\] info=onSwapCommitted OK: currentPlacementId <P> ->' within 30s`.
 - Lý do: chỉ đóng do người dùng bấm mới reload; `Ads.dismissByPlacement()` (nút `Dismiss` của màn test) thì không (`SA/show/ReloadCoordinator.kt:225-229`).
 
@@ -38,7 +38,7 @@ Mỗi kịch bản ghi `needs` (điều kiện config). Đọc config trước k
 - steps: bật premium → show `<P>` → `expect log '\[RuleMg Block\] action=SHOW .*code = 103'` → `never '...Impression: public=<P> '`.
 
 ## S6. Mất mạng (104)
-- needs: **máy thật qua USB** (xem `network` trong [scenario-format.md](scenario-format.md)).
+- needs: **máy thật qua USB** (xem `network` trong [scenario-format.md](../references/scenario-format.md)).
 - steps: `network off` → show `<P>` → `expect log '\[RuleMg Block\] action=SHOW .*code = 104' within 5s` → `network on` (luôn chạy, kể cả khi fail).
 
 ## Báo cáo mỗi kịch bản