@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/skills/super-ads-add-placement/SKILL.md

@@ -1,57 +1,63 @@
 ---
 schema: 1
 name: super-ads-add-placement
-description: Use when an app that already runs SuperAds needs a new ad placement or a placement moved/changed — config via the super-ads MCP, call site in app code, then verification on device.
-version: 1.0.0
+description: Use when an app already on SuperAds needs a new or changed ad placement - MCP config, call site, device check
+version: 1.1.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Gắn thêm placement vào app đã dùng SuperAds
 
 Ba phần luôn đi cùng nhau: **config** (placement + adItem + unit), **call site** (lời gọi `Ads.show` / `Ads.dispatchEvent` trong code app), **kiểm tra** trên thiết bị.
 
-| Bước | Tài liệu |
+## When to use
+
+- "Thêm inter khi bấm nút X", "thêm native vào màn Y", "đổi banner sang collapsible", "thêm app open".
+
+## 🚫 When NOT to use
+
+- App chưa có SuperAds → [super-ads-integrate](../super-ads-integrate/SKILL.md).
+- App còn AdsPro → `adspro-to-superads`.
+- Chỉ chỉnh tần suất / giá trị key của placement có sẵn, không đụng code: [super-ads-config](../super-ads-config/SKILL.md) (và `super-ads-show-rate` nếu cần đo trước/sau).
+
+## 📋 Prerequisites
+
+- Đị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`. Nếu app dùng SuperAds 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.
+- Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+- Thứ tự nguồn sự thật: (1) code SDK (`SA/api/…`), (2) `MIGRATION.md`, (3) tri thức key và `format-playbooks.md`, (4) code hiện có của app: wrapper, quy ước đặt tên placement, cách các màn khác đang gọi ad. Code app quyết định **cách viết**, SDK quyết định **hành vi**.
+- Recon trước: file config đang nạp, placement có sẵn, wrapper của app, một màn tương tự đã gắn ad (Bước 1 của Workflow).
+- MCP `super-ads` đang kết nối.
+
+## ⚡ Quick Reference
+
+| Cần | Mở |
 |---|---|
-| Call site theo format | [references/call-site-snippets.md](references/call-site-snippets.md) |
+| API `Ads.show`, `AdTarget`, callback, inline trong list | [references/call-site-api.md](references/call-site-api.md) |
+| Fullscreen có điều hướng (INTER, NATIVE_FULL_ACTIVITY) | [snippets/fullscreen-nav.md](snippets/fullscreen-nav.md) |
+| Reward / Reward Interstitial | [snippets/reward.md](snippets/reward.md) |
+| Inline: banner, native, collapsible | [snippets/inline-banner-native.md](snippets/inline-banner-native.md) |
+| Preload theo event | [snippets/preload-event.md](snippets/preload-event.md) |
+| App Open khi quay lại app | [snippets/app-open.md](snippets/app-open.md) |
 | Chọn format, recipe config | `tools/ai_agent_tools/docs/format-playbooks.md`, MCP `list_ad_formats` / `get_format_recipe` |
 | Quy trình MCP (patch, conflict, sync) | `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` |
-| Ý nghĩa key, placement, tác động patch | MCP `explain_key` / `explain_placement` / `impact_of_patch` (`tools/ai_agent_tools/src/mcp/tools.js:177-219`); nguồn: `tools/ai_agent_tools/data/ads_key_knowledge.json` |
-| Kiểm trên máy | `super-ads-adb-test` |
+| Kiểm trên máy | [super-ads-adb-test](../super-ads-adb-test/SKILL.md) |
 
-Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+## 🏗️ Recommended Architecture
 
-## When to use
-- "Thêm inter khi bấm nút X", "thêm native vào màn Y", "đổi banner sang collapsible", "thêm app open".
+Một placement mới là ba phần cùng đổi, theo thứ tự:
 
-## When NOT to use
-- App chưa có SuperAds → `super-ads-integrate`.
-- App còn AdsPro → `adspro-to-superads`.
-- Chỉ chỉnh tần suất / giá trị key của placement có sẵn, không đụng code: `super-ads-config` (và `super-ads-show-rate` nếu cần đo trước/sau).
-
-## Authority order
-1. Code SDK (`SA/api/…`).
-2. `MIGRATION.md`.
-3. Tri thức key và `format-playbooks.md`.
-4. Code hiện có của app: wrapper, quy ước đặt tên placement, cách các màn khác đang gọi ad. Code app quyết định **cách viết**, SDK quyết định **hành vi**.
-
-## Contract
-**MUST**
-- Recon trước: file config đang nạp, placement có sẵn, wrapper của app, một màn tương tự đã gắn ad.
-- Đổi config **chỉ** qua MCP `super-ads` (`scaffold_ad` → `impact_of_patch` → user duyệt → `apply_patch` → `validate_config` → `sync_to_source`; `create_ad` chỉ trong ca ở Phase 3). Không sửa tay file JSON.
-- `impact_of_patch` trước **mọi** `apply_patch`. User duyệt đúng patch đó rồi mới áp.
-- `validate_config` sạch error trước khi `sync_to_source`.
-- Call site theo wrapper của app nếu có. Không có thì theo [call-site-snippets.md](references/call-site-snippets.md).
-- Placement id trong code trùng **chính xác** id trong config (phân biệt hoa thường).
-- Inline: truyền `AdTarget.AdView(container, lifecycle)`; trong Fragment dùng `viewLifecycleOwner.lifecycle`.
-- Fullscreen chặn luồng (sang màn sau, nhận thưởng): xử lý cả nhánh fail. Ad lỗi không được làm kẹt người dùng.
+1. **Config** (qua MCP): `scaffold_ad` → `impact_of_patch` → user duyệt → `apply_patch` → `validate_config` → `sync_to_source`.
+2. **Call site** (code app): theo wrapper của app nếu có, không thì theo [snippets](references/call-site-api.md).
+3. **Kiểm trên máy**: show → Impression, cộng một kịch bản fail.
 
-**MUST NOT**
-- Không bịa ad unit id. Không lấy unit của app khác.
-- Không dùng unit test `ca-app-pub-3940256099942544` trong config sẽ phát hành.
-- Không thêm network/plugin mới (dependency) khi chưa hỏi.
-- Không gọi `Ads.show` song song với wrapper đã có cho cùng việc.
+Placement id trong code phải trùng chính xác id trong config.
+
+## Workflow
+
+### Stop conditions (dừng và hỏi user)
 
-## Stop conditions (dừng và hỏi user)
 - Thiếu ad unit id thật, hoặc chưa rõ network.
 - `validate_config` báo lỗi mà cách sửa đổi hành vi placement khác.
 - Thay đổi ảnh hưởng nhiều hơn 1 placement (dùng chung adItem, `reload.*`, chain, `show.keyTimeBetween`).
@@ -60,15 +66,15 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
 - App có wrapper riêng mà chưa rõ cách dùng, hoặc không có màn nào tương tự để theo.
 - Quyết định sản phẩm: vị trí, thời điểm show, tần suất, có thưởng khi đóng sớm hay không (`RewardAdCallback.applyForAnyAdFull`).
 
-## Phase 1: Recon
+### 1. Recon
+
 1. Tìm `Ads.init` (và `Ads.loadFromJson`) trong `Application` → tên file config (asset) và có remote hay không.
 2. `read_working_config` (MCP): placement có sẵn, quy ước đặt tên, network đang dùng, và `defaultSyncPath` có đúng file ở bước 1 không. `explain_placement` cho placement mẫu nếu cần hiểu key của nó.
 3. Tìm wrapper: grep `Ads.show(` trong app. Nhiều chỗ gọi qua cùng một hàm thì đó là wrapper.
 4. Chọn một màn đã gắn ad cùng nhóm format làm mẫu.
 
-**Verify:** ghi được: file config (và `defaultSyncPath` có khớp không), placement mẫu, hàm wrapper (hoặc "không có"), màn mẫu.
+### 2. Chọn format
 
-## Phase 2: Chọn format
 | Nhu cầu | Format | Ghi chú |
 |---|---|---|
 | Chen giữa hai màn | `INTER` (hoặc `NATIVE_FULL_ACTIVITY`) | `NavAdCallback`, key `mode.navigate` |
@@ -80,9 +86,8 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
 
 Danh sách format thật: `SA/domain/model/ad/AdFormat.kt:12`. Recipe config: MCP `get_format_recipe`.
 
-**Verify:** format, network, unit id đã chốt với user.
+### 3. Config qua MCP
 
-## Phase 3: Config qua MCP
 1. Sinh patch: `scaffold_ad` với id theo quy ước của app, cộng các key theo recipe. Mỗi key không có trong recipe: `explain_key` (truyền `format`), ghi `confidence`; `confidence` khác `verified` hoặc `appliesToFormat` khác `true` thì nói rõ với user.
 2. `impact_of_patch` với đúng patch sẽ áp.
    - `mustAsk = true` ⇒ dừng, hỏi user nguyên văn từng mục `askReasons`.
@@ -92,30 +97,85 @@ Danh sách format thật: `SA/domain/model/ad/AdFormat.kt:12`. Recipe config: MC
    - `create_ad` (tự apply, không qua `impact_of_patch`) chỉ dùng khi không ai khác đang sửa song song (`tools/ai_agent_tools/src/mcp/tools.js:284-291`) **và** chỉ tạo entity mới, user đã duyệt spec (format, network, unit, id).
 4. `validate_config` → sửa đến khi hết error (mỗi lần sửa lại qua bước 2-3). `explain_placement` cho placement mới để kiểm `issues` / `unresolved`.
 5. Trình user diff thực tế (`diff_configs` hoặc `history`). Khác diff đã duyệt ⇒ không sync, hỏi lại.
-6. `sync_to_source`: trước đó `read_working_config`, kiểm `defaultSyncPath` đúng file config app nạp (Phase 1); không đúng thì truyền `targetPath`.
+6. `sync_to_source`: trước đó `read_working_config`, kiểm `defaultSyncPath` đúng file config app nạp (Bước 1); không đúng thì truyền `targetPath`.
 
-**Verify:** `validate_config` không error; file config trên đĩa (đúng file app nạp) có placement mới.
+### 4. Call site
 
-## Phase 4: Call site
-- Viết theo wrapper hoặc mẫu trong [call-site-snippets.md](references/call-site-snippets.md).
+- Viết theo wrapper hoặc mẫu trong [references/call-site-api.md](references/call-site-api.md) (snippet theo format ở bảng Quick Reference).
 - Preload: thêm `Ads.dispatchEvent(activity, "<event>")` ở chỗ app biết sắp cần ad, event khớp `preload.eventActive`.
 - Build module app: `./gradlew :<appModule>:assembleDebug`. Báo nguyên văn kết quả.
 
-**Verify:** build pass; grep thấy placement id trong code và trong config.
+### 5. Kiểm trên máy
 
-## Phase 5: Kiểm trên máy
-- Chạy `super-ads-adb-test`: ít nhất kịch bản "show → Impression" cho placement mới, và một kịch bản fail (mất mạng hoặc cooldown) để chắc nhánh fail không làm kẹt người dùng.
+- Chạy [super-ads-adb-test](../super-ads-adb-test/SKILL.md): ít nhất kịch bản "show → Impression" cho placement mới, và một kịch bản fail (mất mạng hoặc cooldown) để chắc nhánh fail không làm kẹt người dùng.
 - Không có máy: ghi **chưa kiểm trên thiết bị**.
 
-**Verify:** có dòng `adEventSink Impression: public=<placement>` (`SA/show/AdEventRouter.kt:67`), hoặc ghi rõ là chưa chạy.
+## 🔧 API Reference
+
+| MCP tool | Mục đích |
+|---|---|
+| `read_working_config` | Xem config đang làm việc, `defaultSyncPath` |
+| `list_ad_formats` / `get_format_recipe` | Chọn format, recipe config |
+| `scaffold_ad` | Sinh patch cho placement mới |
+| `explain_key` / `explain_placement` / `impact_of_patch` | Ý nghĩa key, placement, tác động patch (`tools/ai_agent_tools/src/mcp/tools.js:177-219`); nguồn: `tools/ai_agent_tools/data/ads_key_knowledge.json` |
+| `apply_patch` | Áp patch đã duyệt |
+| `validate_config` | Kiểm config trước khi sync |
+| `diff_configs` / `history` | Diff thực tế, lịch sử thay đổi |
+| `sync_to_source` | Ghi vào file config app nạp |
+| `create_ad` | Tạo entity mới (tự apply), chỉ trong ca ở bước 3 |
+
+Call site (`Ads.show`, `AdTarget`, callback): [references/call-site-api.md](references/call-site-api.md).
+
+## ✅ Best Practices
+
+- Đổi config **chỉ** qua MCP `super-ads` (`scaffold_ad` → `impact_of_patch` → user duyệt → `apply_patch` → `validate_config` → `sync_to_source`; `create_ad` chỉ trong ca ở Bước 3). Không sửa tay file JSON.
+- `impact_of_patch` trước **mọi** `apply_patch`. User duyệt đúng patch đó rồi mới áp.
+- `validate_config` sạch error trước khi `sync_to_source`.
+- Call site theo wrapper của app nếu có. Không có thì theo [call-site-api.md](references/call-site-api.md).
+- Placement id trong code trùng **chính xác** id trong config (phân biệt hoa thường).
+- Inline: truyền `AdTarget.AdView(container, lifecycle)`; trong Fragment dùng `viewLifecycleOwner.lifecycle`.
+- Fullscreen chặn luồng (sang màn sau, nhận thưởng): xử lý cả nhánh fail. Ad lỗi không được làm kẹt người dùng.
+
+## ❌ Anti-patterns
 
-## Anti-patterns
+- Bịa ad unit id, hoặc lấy unit của app khác.
+- Dùng unit test `ca-app-pub-3940256099942544` trong config sẽ phát hành.
+- Thêm network/plugin mới (dependency) khi chưa hỏi.
+- Gọi `Ads.show` song song với wrapper đã có cho cùng việc.
 - Thêm placement vào config mà quên call site (hoặc ngược lại).
 - Copy placement có sẵn rồi đổi tên nhưng vẫn dùng chung adItem: hai placement chung cooldown và bộ đếm.
 - `mode.show = SHOW_LOADED` mà không có `Ads.dispatchEvent` tương ứng: fail `LOAD:208` mãi.
 - Gắn inline vào container `GONE` hoặc kích thước 0.
 
+## ⚠️ Common Issues
+
+**`apply_patch` trả `VERSION_CONFLICT`.**
+Cause: config đã đổi từ lúc đọc. Solution: `read_working_config` + `history`, dựng lại patch, `impact_of_patch` lại (chi tiết ở Workflow bước 3).
+
+**Placement fail `LOAD:208` mãi.**
+Cause: `mode.show = SHOW_LOADED` mà chưa có `Ads.dispatchEvent` tương ứng. Solution: thêm `Ads.dispatchEvent` đúng `preload.eventActive`, hoặc dùng `LOAD_AND_SHOW` ([snippets/preload-event.md](snippets/preload-event.md)).
+
+## Files created
+
+- Không tạo file source mới. Placement mới là entry thêm vào file config hiện có (qua MCP), không phải file riêng.
+
+## Files modified
+
+- File config (asset) app đang nạp: ghi qua MCP `sync_to_source`, không sửa tay.
+- Code app tại call site (hoặc wrapper của app): lời gọi `Ads.show` / `Ads.dispatchEvent`.
+
+## Verification
+
+Báo output thật. Sau mỗi bước ở Workflow:
+
+1. **Recon:** ghi được: file config (và `defaultSyncPath` có khớp không), placement mẫu, hàm wrapper (hoặc "không có"), màn mẫu.
+2. **Chọn format:** format, network, unit id đã chốt với user.
+3. **Config qua MCP:** `validate_config` không error; file config trên đĩa (đúng file app nạp) có placement mới.
+4. **Call site:** build pass; grep thấy placement id trong code và trong config.
+5. **Kiểm trên máy:** có dòng `adEventSink Impression: public=<placement>` (`SA/show/AdEventRouter.kt:67`), hoặc ghi rõ là chưa chạy.
+
 ## Checklist
+
 - [ ] Recon xong, có màn mẫu.
 - [ ] Format, network, unit id đã chốt.
 - [ ] `impact_of_patch` cho mọi patch, user duyệt đúng patch đó (`mustAsk` đã hỏi).
@@ -124,5 +184,40 @@ Danh sách format thật: `SA/domain/model/ad/AdFormat.kt:12`. Recipe config: MC
 - [ ] Build pass (trích output).
 - [ ] Đã kiểm trên máy, hoặc ghi rõ chưa.
 
+## 📈 Performance Notes
+
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+
+> **Not applicable for this skill.**
+
 ## Output
+
 File đã sửa (code app, config), diff config, output build, kết quả kiểm trên máy, phần chưa xác minh.
+
+## Examples
+
+- Fullscreen có điều hướng: [snippets/fullscreen-nav.md](snippets/fullscreen-nav.md)
+- Reward: [snippets/reward.md](snippets/reward.md)
+- Inline: [snippets/inline-banner-native.md](snippets/inline-banner-native.md)
+- Preload theo event: [snippets/preload-event.md](snippets/preload-event.md)
+- App Open: [snippets/app-open.md](snippets/app-open.md)
+- Inline trong danh sách: [references/call-site-api.md](references/call-site-api.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-integrate](../super-ads-integrate/SKILL.md), [super-ads-config](../super-ads-config/SKILL.md), [super-ads-adb-test](../super-ads-adb-test/SKILL.md).
+- `adspro-to-superads`, `super-ads-show-rate`: skill anh em.
+- Mẫu wrapper: [../adspro-to-superads/references/wrapper-template.md](../adspro-to-superads/references/wrapper-template.md).
+- Repo SDK: `MIGRATION.md`, `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`, `tools/ai_agent_tools/docs/format-playbooks.md`.
+
+## 🏷️ Tags
+
+`superads`, `placement`, `mcp`, `call-site`, `config`, `ads`

package/skills/super-ads-add-placement/references/call-site-api.md

@@ -0,0 +1,33 @@
+# Call site theo nhóm format
+
+> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
+
+## API dùng chung
+
+| API | Chữ ký / hành vi | Nguồn |
+|---|---|---|
+| `Ads.show` | `show(placementId, activity, target = AdTarget.AdFull, callback = LoggerAdsCallback())`; callback chạy trên main; gọi trước khi init xong thì xếp hàng chờ | `SA/api/Ads.kt:200-217` |
+| `AdTarget` | `AdFull` (fullscreen) hoặc `AdView(container, lifecycleOfViewOwner = null)` (inline) | `SA/api/model/AdTarget.kt:7-15` |
+| `AdsCallback` | `onAdImpression`, `onAdShowedFull`, `onAdDismissedFull`, `onAdCollapsibleDismiss`, `onAdFailed`, `onUserEarnedReward`, `onAdClicked` (đều có thân mặc định) | `SA/api/callback/AdsCallback.kt:32-120` |
+| `NavAdCallback` | gọi `onNav` một lần theo `mode.navigate`; fail thì `NavResult.Failed` | `SA/api/callback/AdsCallback.kt:122-191` |
+| `RewardAdCallback` | gọi `onReward` một lần lúc dismiss; `Premium` coi là `Success` | `SA/api/callback/AdsCallback.kt:194-266` |
+| `Ads.dispatchEvent` | preload các adItem có `preload.eventActive` chứa event | `SA/api/Ads.kt:247-249` |
+| `Ads.destroyByPlacement` / `Ads.dismissByPlacement` | huỷ ad + cache của placement / đóng ad đang hiện và dừng reload | `SA/api/Ads.kt:225-237` |
+
+## Snippet theo nhóm format
+
+| Nhóm format | Snippet |
+|---|---|
+| Fullscreen có điều hướng (INTER, NATIVE_FULL_ACTIVITY) | [../snippets/fullscreen-nav.md](../snippets/fullscreen-nav.md) |
+| Reward / Reward Interstitial | [../snippets/reward.md](../snippets/reward.md) |
+| Inline: banner, native, collapsible | [../snippets/inline-banner-native.md](../snippets/inline-banner-native.md) |
+| Preload theo event | [../snippets/preload-event.md](../snippets/preload-event.md) |
+| App Open khi quay lại app | [../snippets/app-open.md](../snippets/app-open.md) |
+| Inline trong danh sách (RecyclerView / Epoxy) | mục "Inline trong danh sách" bên dưới |
+
+## Inline trong danh sách (RecyclerView / Epoxy)
+
+Mẫu: `app/src/main/java/com/android/hd/ads2026/test/NativeTestActivity.kt:49-65`.
+- Gọi `Ads.show` lúc bind item quảng cáo, với container của chính item đó.
+- Trả placement khi unbind (`AdPlacementController.recyclePlacement`, `app/src/main/java/com/android/hd/ads2026/AdPlacementController.kt:131`). Đây là helper của app mẫu, không thuộc SDK.

package/skills/super-ads-add-placement/snippets/app-open.md

@@ -0,0 +1,25 @@
+# App Open khi quay lại app
+
+> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
+
+API dùng chung: [../references/call-site-api.md](../references/call-site-api.md).
+
+```kotlin
+// Application.onCreate, sau Ads.init
+// appOpenAllowed: cờ của app, chỉ bật sau callback consent và sau lần vào app đầu (splash).
+AppLifecycleMonitor(
+    onForeground = {
+        if (appOpenAllowed) {
+            Ads.config.getActivityProvider()?.getActivityOnTopNotAds()?.let { Ads.show("<app_open_placement>", it) }
+        }
+    },
+    onBackground = {},
+).register()
+```
+
+**Không bỏ guard:** `onForeground` chạy cả ở `ON_START` đầu tiên lúc mở app lạnh (`SA/api/lifecycle/AppLifecycleMonitor.kt:19-21`), tức trước khi consent ở Activity đầu kịp trả về. Không có guard thì App Open gửi request trước consent. App mẫu chặn tạm bằng thời gian (`app/src/main/java/com/android/hd/ads2026/MyApplication.kt:61`).
+
+- `AppLifecycleMonitor` chỉ chuyển `onStart`/`onStop` của `ProcessLifecycleOwner` (`SA/api/lifecycle/AppLifecycleMonitor.kt:9-29`). Mẫu đăng ký: `app/src/main/java/com/android/hd/ads2026/MyApplication.kt:58-72`.
+- Guard sau fullscreen (`appOpen.guardAfterFullscreenMs`) chặn App Open ngay sau khi đóng một fullscreen (`POLICY:108`, `SA/engine/rules/FullscreenRules.kt:74-97`).
+- Điều kiện thêm (màn splash, không show lần mở đầu…) là logic của app: theo cách app đang làm, chưa có thì hỏi user.

package/skills/super-ads-add-placement/snippets/fullscreen-nav.md

@@ -0,0 +1,14 @@
+# Fullscreen có điều hướng (INTER, NATIVE_FULL_ACTIVITY)
+
+> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
+
+API dùng chung: [../references/call-site-api.md](../references/call-site-api.md).
+
+```kotlin
+Ads.show("<placement>", activity, callback = NavAdCallback { result ->
+    goNext()   // gọi cho cả Success và Failed: ad lỗi không được chặn luồng người dùng
+})
+```
+
+Thời điểm `onNav` do key `mode.navigate` quyết định, SDK không tự điều hướng (tra `mode.navigate` trong `tools/ai_agent_tools/data/ads_key_knowledge.json`).

package/skills/super-ads-add-placement/snippets/inline-banner-native.md

@@ -0,0 +1,19 @@
+# Inline: banner, native, collapsible
+
+> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
+
+API dùng chung: [../references/call-site-api.md](../references/call-site-api.md).
+
+```kotlin
+// Activity
+Ads.show("<placement>", this, AdTarget.AdView(binding.adContainer, lifecycle), object : AdsCallback {
+    override fun onAdFailed(placementId: String, error: AdError) { binding.adContainer.isVisible = false }
+})
+
+// Fragment: dùng lifecycle của VIEW, không phải của fragment
+Ads.show("<placement>", requireActivity(), AdTarget.AdView(binding.adContainer, viewLifecycleOwner.lifecycle))
+```
+
+- Mẫu thật: `app/src/main/java/com/android/hd/ads2026/test/BaseTestActivity.kt:79-84`.
+- SDK theo dõi lifecycle chủ view chỉ với collapsible và banner collapsible. Banner/native thường **không** theo dõi (`SA/presentation/presenter/InlinePresenter.kt:23-27`). Dọn ad khi màn hình chết thì theo cách app đang làm ở các màn khác; chưa có tiền lệ thì hỏi user.

package/skills/super-ads-add-placement/snippets/preload-event.md

@@ -0,0 +1,13 @@
+# Preload theo event
+
+> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
+
+API dùng chung: [../references/call-site-api.md](../references/call-site-api.md).
+
+```kotlin
+Ads.dispatchEvent(activity, "<event>")   // event phải nằm trong preload.eventActive của adItem
+```
+
+- Mẫu: `app/src/main/java/com/android/hd/ads2026/test/BaseTestActivity.kt:87-92`.
+- `mode.show = SHOW_LOADED` thì show **chỉ** dùng ad đã preload; chưa có thì fail `LOAD:208`. Muốn load lúc show thì dùng `LOAD_AND_SHOW` (tra `mode.show` trong file tri thức).

package/skills/super-ads-add-placement/snippets/reward.md

@@ -0,0 +1,17 @@
+# Reward / Reward Interstitial
+
+> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
+> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
+
+API dùng chung: [../references/call-site-api.md](../references/call-site-api.md).
+
+```kotlin
+Ads.show("<placement>", activity, callback = RewardAdCallback(applyForAnyAdFull = false) { result ->
+    when (result) {
+        is RewardResult.Success -> grantReward()
+        is RewardResult.Failed -> showNoReward()
+    }
+})
+```
+
+`applyForAnyAdFull = true` (mặc định) cho thưởng cả khi đóng ad mà không nhận reward (`SA/api/callback/AdsCallback.kt:194-199`). Chọn giá trị là **quyết định sản phẩm**, phải hỏi user.

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

@@ -1,54 +1,53 @@
 ---
 schema: 1
 name: super-ads-config
-description: Use when an existing SuperAds config needs a value changed, an entity enabled/disabled/removed, or any patch applied through the super-ads MCP — explain, compute impact, get the user's approval for that exact patch, apply, verify, then sync.
-version: 1.0.0
+description: Use when an existing SuperAds config needs a value changed, an entity toggled or removed via the super-ads MCP
+version: 1.1.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Sửa config SuperAds qua MCP, có điểm dừng bắt buộc
 
 Mỗi thay đổi config đi đúng một vòng: **hiểu** (`explain_*`) → **tính tác động** (`impact_of_patch`) → **user duyệt đúng patch đó** → **áp** (`apply_patch`) → **kiểm lại** (`history`, `validate_config`) → **sync**. Điểm dừng do tool quyết định (`mustAsk`), không do agent tự đánh giá.
 
-| Cần | Tài liệu |
-|---|---|
-| Output thật của `impact_of_patch` (3 ca) | [references/patch-examples.md](references/patch-examples.md) |
-| Quy trình MCP chung (conflict, cộng tác, sync) | `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` |
-| Ý nghĩa key | MCP `explain_key`; nguồn `tools/ai_agent_tools/data/ads_key_knowledge.json` |
-| Tool | `explain_key` / `explain_placement` / `impact_of_patch` (`tools/ai_agent_tools/src/mcp/tools.js:177-219`), `apply_patch` (`tools/ai_agent_tools/src/mcp/tools.js:354-380`) |
-
 ## When to use
 - "Tăng cooldown inter lên 60 s", "tắt placement X", "đổi timeout load của adItem Y", "xoá adItem cũ", mọi patch lên working config.
 
-## When NOT to use
+## 🚫 When NOT to use
 - Thêm placement mới kèm call site trong code → `super-ads-add-placement` (skill đó dùng lại vòng này cho phần config).
 - Đo show rate trước/sau → `super-ads-show-rate`.
 - Ad lỗi một lần cụ thể → `super-ads-debug`.
 - Tạo config từ đầu (`create_config`) → `super-ads-integrate`.
 
-## 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.
+- MCP `super-ads` đã kết nối (các tool `read_working_config`, `explain_key`, `explain_placement`, `impact_of_patch`, `apply_patch`, `history`, `validate_config`, `sync_to_source`).
+- Quy trình MCP chung (conflict, cộng tác, sync): `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`.
+
+## ⚡ Quick Reference
+
+| Cần | Tài liệu |
+|---|---|
+| Output thật của `impact_of_patch` (3 ca) | [examples/patch-examples.md](examples/patch-examples.md) |
+| Quy trình MCP chung | `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md` |
+| Ý nghĩa key | MCP `explain_key`; nguồn `tools/ai_agent_tools/data/ads_key_knowledge.json` |
+
+Skill này không có `references/`, `templates/`, `snippets/` hay `scripts/`: ví dụ duy nhất nằm trong `examples/`.
+
+## 🏗️ Recommended Architecture
+Vòng xử lý: `read_working_config` → `explain_*` → `impact_of_patch` → user duyệt → `apply_patch` → `history` + `validate_config` → `sync_to_source`. Mỗi bước có **Verify** ở phần Workflow.
+
+Thứ tự thẩm quyền khi các nguồn mâu thuẫn:
 1. Kết quả tool MCP (`impact_of_patch`, `validate_config`): quyết định có phải dừng hay không.
 2. Code SDK, qua `explain_key` (`confidence`, `sdkSource`).
 3. `AI_ADS_PLAYBOOK.md`.
 4. Lời user trong hội thoại: quyết định **giá trị** và **có áp hay không**.
 
-## Contract
-**MUST**
-- `impact_of_patch` với **đúng** patch sắp áp, trước mọi `apply_patch`. `ok:false` (`PATCH_INVALID`) thì dừng, sửa patch; kết quả lỗi không bao giờ được coi là an toàn.
-- Trình user trước khi áp: patch, `changedPaths`, `affectedPlacements`, hành vi dự kiến (từ `explain_key.effect`), `confidence` của từng key, rủi ro.
-- `mustAsk = true`: hỏi **nguyên văn từng** câu trong `askReasons`, nhận câu trả lời rõ cho từng câu.
-- `apply_patch` với `baseVersion` đọc được ở bước 1 và đúng patch đã duyệt.
-- Sau khi áp: so op trong `history` (theo `opId` trả về) với patch đã duyệt.
-- `validate_config` sạch error trước `sync_to_source`; `defaultSyncPath` đúng file app nạp.
-
-**MUST NOT**
-- **`mustAsk = false` không phải quyền tự sửa.** Mọi `apply_patch` cần user duyệt đúng patch đó. Câu duyệt chung trước đó ("cứ sửa đi") không thay được duyệt patch, cũng không thay được câu trả lời cho từng `askReasons`.
-- **Không retry mù khi `VERSION_CONFLICT`.** Đọc lại, tính lại impact; patch hoặc tác động đổi thì xin duyệt lại. Không dùng `replace_working_config` để ghi đè.
-- **Không `sync_to_source` khi diff thực tế khác diff đã duyệt.**
-- Không sửa tay file JSON. Không tự chọn giá trị thay user (cooldown, maxShow, unit id).
-- Không đổi patch sau khi user duyệt mà không chạy lại `impact_of_patch` và xin duyệt lại.
+## Workflow
 
-## Stop conditions (dừng và hỏi user)
+### Stop conditions (dừng và hỏi user)
 - `impact_of_patch.mustAsk = true`: mỗi `askReasons[].rule` là một câu hỏi:
 
 | `rule` | Ý nghĩa |
@@ -64,26 +63,26 @@ Mỗi thay đổi config đi đúng một vòng: **hiểu** (`explain_*`) → **
 - Op trong `history` khác patch đã duyệt.
 - Hoàn tác bị từ chối (`PATCH_INVALID`, code `TEST_FAILED`): path đã bị actor khác đổi.
 
-## Phase 1: Đọc
+### Phase 1: Đọc
 1. `read_working_config` → ghi `version` (dùng làm `baseVersion`), `defaultSyncPath`.
 2. `explain_placement` cho placement liên quan (`issues`, `unresolved`); `explain_key` (kèm `format`) cho từng key sẽ đổi.
 
 **Verify:** ghi được `baseVersion`, placement đích, nghĩa và `confidence` của từng key.
 
-## Phase 2: Tính tác động
+### Phase 2: Tính tác động
 1. Soạn patch JSON Patch (RFC 6902), path tới key phẳng có dấu chấm: `/adItems/<id>/config/show.timeBetweenMs`.
 2. `impact_of_patch {patch}` (mặc định chạy trên workspace, trả kèm `baseVersion`). `baseVersion` khác bước 1 ⇒ quay lại Phase 1.
 
 **Verify:** có `ok:true`, `changedPaths` đúng các path định đổi, `affectedPlacements` đã đọc.
 
-## Phase 3: Duyệt
+### Phase 3: Duyệt (điểm dừng bắt buộc)
 1. Trình: patch, `changedPaths`, `affectedPlacements` (kèm `reasons`), hành vi dự kiến, `confidence`, rủi ro.
 2. `mustAsk = true` ⇒ hỏi nguyên văn từng `askReasons[].text`. `mustAsk = false` ⇒ vẫn hỏi "áp đúng patch này?".
 3. Chỉ sang Phase 4 khi user đồng ý **đúng patch đã trình**. User sửa giá trị ⇒ quay lại Phase 2.
 
 **Verify:** có câu trả lời rõ cho patch và cho từng `askReasons`.
 
-## Phase 4: Áp
+### Phase 4: Áp
 `apply_patch {baseVersion, patch, summary}`. Đang cộng tác với một phiên `open_editor` thì truyền `editorSessionId` (xem `AI_ADS_PLAYBOOK.md`).
 
 | Kết quả | Làm gì |
@@ -93,7 +92,7 @@ Mỗi thay đổi config đi đúng một vòng: **hiểu** (`explain_*`) → **
 | `VALIDATION_FAILED` | Dừng, trình `validation` |
 | `PATCH_INVALID` | Dừng, patch sai path/op |
 
-## Phase 5: Kiểm sau khi áp
+### Phase 5: Kiểm sau khi áp
 1. `history {sinceVersion: <baseVersion>}` → record có `opId` vừa nhận: `patch` và `changedPaths` phải khớp bản đã duyệt; không có op nào khác của actor khác chen vào cùng path.
 2. Khác ⇒ dừng, báo user, đề nghị hoàn tác:
    - Đã áp kèm `editorSessionId`: `undo_last_change {editorSessionId}` (`tools/ai_agent_tools/src/mcp/tools.js:403-419`).
@@ -102,7 +101,7 @@ Mỗi thay đổi config đi đúng một vòng: **hiểu** (`explain_*`) → **
 
 **Verify:** op khớp patch đã duyệt; `validate_config.errors` rỗng.
 
-## Phase 6: Sync
+### Phase 6: Sync
 1. Chưa chạy thử trên máy ⇒ hỏi user có cần kiểm trước không (`super-ads-adb-test`). Không tự bỏ qua câu hỏi này.
 2. Trình diff thực tế (`diff_configs` hoặc op trong `history`). Khác diff đã duyệt ⇒ không sync.
 3. `read_working_config`: `defaultSyncPath` đúng file app nạp? Không đúng ⇒ truyền `targetPath`.
@@ -110,15 +109,54 @@ Mỗi thay đổi config đi đúng một vòng: **hiểu** (`explain_*`) → **
 
 **Verify:** file trên đĩa (đúng file app nạp) có thay đổi; không còn thay đổi ngoài patch đã duyệt.
 
-## Anti-patterns
+## 🔧 API Reference
+
+| Tool | Mục đích | Nguồn |
+|---|---|---|
+| `explain_key` / `explain_placement` / `impact_of_patch` | Hiểu key, placement và tính tác động của patch | `tools/ai_agent_tools/src/mcp/tools.js:177-219` |
+| `apply_patch` | Áp đúng patch đã duyệt lên working config | `tools/ai_agent_tools/src/mcp/tools.js:354-380` |
+| `read_working_config`, `history`, `validate_config`, `diff_configs`, `undo_last_change`, `sync_to_source` | Đọc, đối soát, kiểm và đồng bộ | Phase 1, 5, 6 ở trên |
+
+## ✅ Best Practices
+- `impact_of_patch` với **đúng** patch sắp áp, trước mọi `apply_patch`. `ok:false` (`PATCH_INVALID`) thì dừng, sửa patch; kết quả lỗi không bao giờ được coi là an toàn.
+- Trình user trước khi áp: patch, `changedPaths`, `affectedPlacements`, hành vi dự kiến (từ `explain_key.effect`), `confidence` của từng key, rủi ro.
+- `mustAsk = true`: hỏi **nguyên văn từng** câu trong `askReasons`, nhận câu trả lời rõ cho từng câu.
+- `apply_patch` với `baseVersion` đọc được ở bước 1 và đúng patch đã duyệt.
+- Sau khi áp: so op trong `history` (theo `opId` trả về) với patch đã duyệt.
+- `validate_config` sạch error trước `sync_to_source`; `defaultSyncPath` đúng file app nạp.
+
+## ❌ Anti-patterns
+- **`mustAsk = false` không phải quyền tự sửa.** Mọi `apply_patch` cần user duyệt đúng patch đó. Câu duyệt chung trước đó ("cứ sửa đi") không thay được duyệt patch, cũng không thay được câu trả lời cho từng `askReasons`.
+- **Không retry mù khi `VERSION_CONFLICT`.** Đọc lại, tính lại impact; patch hoặc tác động đổi thì xin duyệt lại. Không dùng `replace_working_config` để ghi đè.
+- **Không `sync_to_source` khi diff thực tế khác diff đã duyệt.**
+- Không sửa tay file JSON. Không tự chọn giá trị thay user (cooldown, maxShow, unit id).
+- Không đổi patch sau khi user duyệt mà không chạy lại `impact_of_patch` và xin duyệt lại.
 - Thấy `mustAsk:false` rồi áp luôn.
 - Gộp nhiều thay đổi không liên quan vào một patch để hỏi một lần.
 - Gặp `VERSION_CONFLICT` thì đổi `baseVersion` rồi gửi lại cùng patch.
 - Đổi `show.timeBetweenMs` ở adItem dùng chung mà chỉ nói về một placement.
 - Gọi `undo_last_change` không có `editorSessionId` cho op AI áp độc lập.
 
-## Giới hạn
-Test (`test/explain.test.js`, `test/skills.test.js`) chứng minh tool tính đúng và skill có đủ quy tắc. Không có test tự động chứng minh agent thật sự dừng ở điểm dừng.
+## ⚠️ Common Issues
+
+| Problem | Cause | Solution |
+|---|---|---|
+| `VERSION_CONFLICT` khi `apply_patch` | Actor khác đã đổi working config sau bước đọc | Phase 1 lại, chạy lại `impact_of_patch`, xin duyệt lại nếu khác |
+| `undo_last_change` không dùng được | Op áp không kèm `editorSessionId` nên không nằm trong stack undo | Dùng `inversePatch` trong `history` qua `impact_of_patch`, user duyệt, `apply_patch` |
+| `inversePatch` bị từ chối (`PATCH_INVALID`, `TEST_FAILED`) | Path đã bị actor khác đổi | Dừng, hỏi user, không ghi đè |
+
+Giới hạn: test (`test/explain.test.js`, `test/skills.test.js`) chứng minh tool tính đúng và skill có đủ quy tắc. Không có test tự động chứng minh agent thật sự dừng ở điểm dừng.
+
+## Files created
+Skill này không tạo file nguồn.
+
+## Files modified
+Không sửa code app. Chỉ file config JSON mà app nạp (`defaultSyncPath` hoặc `targetPath`), qua MCP `apply_patch` rồi `sync_to_source`, đúng patch user đã duyệt. Không sửa tay.
+
+## Verification
+- `history`: op (theo `opId`) khớp patch đã duyệt.
+- `validate_config`: `errors` rỗng.
+- File trên đĩa đúng file app nạp, không còn thay đổi ngoài patch đã duyệt.
 
 ## Checklist
 - [ ] `baseVersion`, nghĩa và `confidence` từng key.
@@ -128,5 +166,25 @@ Test (`test/explain.test.js`, `test/skills.test.js`) chứng minh tool tính đ
 - [ ] `validate_config` sạch.
 - [ ] Đã hỏi về chạy thử; diff thực tế khớp; `sync_to_source` đúng file.
 
+## 📈 Performance Notes
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+> **Not applicable for this skill.**
+
 ## Output
 Patch đã áp, `opId`, `affectedPlacements`, câu trả lời của user cho từng `askReasons`, kết quả `validate_config`, file đã sync, phần chưa xác minh (chưa chạy trên máy…).
+
+## Examples
+- [examples/patch-examples.md](examples/patch-examples.md): output thật của `impact_of_patch` cho 3 ca (`mustAsk: false`, `MULTI_PLACEMENT`, `MONETIZATION_KEY`) và patch lỗi.
+
+## 📚 References
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-upgrade](../super-ads-upgrade/SKILL.md)
+- [super-ads-add-placement](../super-ads-add-placement/SKILL.md), [super-ads-show-rate](../super-ads-show-rate/SKILL.md), [super-ads-debug](../super-ads-debug/SKILL.md), [super-ads-integrate](../super-ads-integrate/SKILL.md), [super-ads-adb-test](../super-ads-adb-test/SKILL.md)
+- `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`, `tools/ai_agent_tools/data/ads_key_knowledge.json`
+
+## 🏷️ Tags
+`super-ads` `config` `mcp` `json-patch` `impact` `approval`