@hungvv/super-ads-skills 1.0.0 → 1.1.0

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

@@ -1,61 +1,56 @@
 ---
 schema: 1
 name: super-ads-debug
-description: Use when an app using SuperAds (com.android.fullhd.ads, object Ads) has ads that do not show, fail to load, render wrong, or behave unexpectedly — evidence-first debugging from logcat, Ads.debug and the debug overlay to an exact error code and fix.
-version: 1.1.0
+description: Use when SuperAds ads do not show, fail to load, render wrong or crash - debug from logs to an error code
+version: 1.2.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Debug SuperAds
 
-Quy trình **bằng chứng trước, kết luận sau**: không đoán nguyên nhân khi chưa có dòng log, event hoặc snapshot chứng minh.
-
-| Bước | Tài liệu |
-|---|---|
-| Bật log, đọc log | [references/logging-setup.md](references/logging-setup.md) |
-| Tra mã lỗi | [references/error-codes.md](references/error-codes.md) |
-| Triệu chứng → bằng chứng | [references/symptom-playbook.md](references/symptom-playbook.md) |
-| Ý nghĩa key config | `tools/ai_agent_tools/data/ads_key_knowledge.json` (bằng chứng: `tools/ai_agent_tools/docs/knowledge-evidence.md`) |
-
-Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `DBG/` = `super-ads-debug/src/main/java/com/android/fullhd/super_ads/debug/`.
+Quy trình **bằng chứng trước, kết luận sau**: không đoán nguyên nhân khi chưa có dòng log, event hoặc snapshot chứng minh. Đi từ logcat / `.logads`, `Ads.debug` và overlay tới đúng mã lỗi và cách sửa.
 
 ## When to use
 - Ad không hiện, hiện lúc có lúc không, load lỗi, hiện sai layout/màu/nút đóng, crash liên quan ads.
 - Cần giải thích một `AdError` / mã lỗi cụ thể.
 
-## When NOT to use
-- Cần **đo tỷ lệ** show (show rate) → `super-ads-show-rate`.
-- Cần viết hoặc chạy kịch bản test lặp lại trên thiết bị → `super-ads-adb-test`.
+## 🚫 When NOT to use
+- Cần **đo tỷ lệ** show (show rate) → [super-ads-show-rate](../super-ads-show-rate/SKILL.md).
+- Cần viết hoặc chạy kịch bản test lặp lại trên thiết bị → [super-ads-adb-test](../super-ads-adb-test/SKILL.md).
 - Thêm placement mới → `super-ads-add-placement`. App chưa có SuperAds → `super-ads-integrate`. App còn AdsPro → `adspro-to-superads`.
 
-## Authority order
+## 📋 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.
+- Ít nhất một nguồn bằng chứng: file `.logads`, Logcat, hoặc log/bằng chứng do user cung cấp. Không tái hiện được mà cũng không có bằng chứng nào thì dừng (xem "Dừng và hỏi user khi" ở Workflow).
+- Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `DBG/` = `super-ads-debug/src/main/java/com/android/fullhd/super_ads/debug/`.
+
+## ⚡ Quick Reference
+| Cần | Mở |
+|---|---|
+| Bật log, đọc log, `name` log, file `.logads` | [references/logging-setup.md](references/logging-setup.md) |
+| Tra mã lỗi | [references/error-codes.md](references/error-codes.md) |
+| Triệu chứng → bằng chứng → nguyên nhân | [references/symptom-playbook.md](references/symptom-playbook.md) |
+| Lọc nhanh file `.logads` (WARN trở lên, hoặc một `name`) | [scripts/filter-logads.sh](scripts/filter-logads.sh) |
+| Ý nghĩa key config | `tools/ai_agent_tools/data/ads_key_knowledge.json` (bằng chứng: `tools/ai_agent_tools/docs/knowledge-evidence.md`) |
+
+## 🏗️ Recommended Architecture
+Thứ tự nguồn sự thật khi các nguồn mâu thuẫn:
 1. Code SDK (`SA/…`, `DBG/…`).
 2. `MIGRATION.md`.
 3. Tri thức key (`ads_key_knowledge.json`; trường `confidence` khác `verified` là suy luận).
 4. Tài liệu và KDoc khác. KDoc có thể đã cũ. Ví dụ: KDoc của `Ads.installDebug` ghi "không có auto-install", nhưng `DBG/DebugInstaller.kt:21-23` tự cài khi có dependency.
 
-## Contract
-**MUST**
-- Có bằng chứng (dòng log `SuperAdsSDK`, `AdShowEvent`, snapshot, callback `onAdFailed`) trước mỗi kết luận, và trích nó trong báo cáo.
-- Phân loại lỗi theo `FailCategory` (`SA/api/debug/AdShowEvent.kt:97-127`): **blocked** (POLICY/CONFIG/INIT, SDK chủ động không show) khác **error** (LOAD/RENDER/BEHAVIOR/GMS/PRELOAD).
-- Thống kê và so sánh theo `category + code`, không theo tên lỗi hay tên rule (tên rule có thể bị R8 đổi).
-- Lỗi LOAD ở `onAdFailed` / `AdShowEvent.Failed` thường là 204, mã con nằm trong `message` ([error-codes.md](references/error-codes.md), mục "Cách đọc").
-- Khi đổi key config: dẫn ý nghĩa và hiệu ứng từ file tri thức. `confidence` khác `verified` thì ghi "suy luận".
-- Tái hiện lại sau khi sửa để xác nhận.
-
-**MUST NOT**
-- Không kết luận "SDK hỏng" khi Logcat trống: kiểm logger trước ([logging-setup.md](references/logging-setup.md) mục 1).
-- Không coi blocked (vd 101 cooldown, 103 premium) là sự cố network.
-- Không sửa config production, `Application`, hay file build khi user chưa đồng ý.
-- Không tăng hay giảm `show.timeBetweenMs`, `load.timeoutMs`… theo cảm tính.
+## Workflow
 
-## Stop conditions (dừng và hỏi user)
+### Dừng và hỏi user khi
 - Không tái hiện được và không có log hoặc bằng chứng nào từ user.
 - Cách sửa đổi hành vi kinh doanh: tần suất ad, `show.maxShow`, tắt placement.
 - Lỗi nằm trong SDK hoặc plugin (crash `RenderCrashed`/`LoadCrashExecute` có stacktrace trong SDK): báo kèm bằng chứng, không tự vá SDK.
 - Cần bật logger hoặc thêm `super-ads-debug` vào app mà app chưa có.
 
-## Phase 1: Bật quan sát
+### Phase 1: Bật quan sát
 1. Tìm lời gọi `Ads.logger.init` trong `Application`. Chưa có, hoặc `enabled = false` / `debug = false`: hỏi user để bật ở bản debug ([logging-setup.md](references/logging-setup.md) mục 2).
 2. Kiểm app có phụ thuộc `super-ads-debug` không (artifact `SuperAdsDebug` hoặc module `:super-ads-debug`).
    - Có: SDK phát `Ads.debug.showEvents`, vì `DebugInstaller` tự cài (`DBG/DebugInstaller.kt:21-23`).
@@ -65,24 +60,24 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `
 
 **Verify:** file `.logads` có dòng lúc init (`ls cache/logads` bằng `run-as`), hoặc `adb logcat -s SuperAdsSDK:V` có dòng lúc init.
 
-## Phase 2: Tái hiện và thu bằng chứng
+### Phase 2: Tái hiện và thu bằng chứng
 - Thực hiện thao tác lỗi rồi lấy file `.logads` mới nhất (`adb exec-out run-as <pkg> cat cache/logads/<file>.logads > ads.logads`; định dạng và cách lọc ở [logging-setup.md](references/logging-setup.md) mục 6). Dự phòng bằng Logcat: `adb logcat -c`, rồi `adb logcat -v time -s SuperAdsSDK:V <AppTag>:V > ads.log` trước khi thao tác.
 - Nếu có `super-ads-debug`:
   - `Ads.debug.showEvents` cho vòng đời từng lần show: `Requested` → `Impression` hoặc `Failed(category, code)` (`SA/api/debug/AdShowEvent.kt`).
   - `Ads.debug.snapshot()` cho showCount, cooldown, cache (`SA/api/AdsFeatures.kt:182-185`). **Không gọi trên main thread**, và hàm trả `null` khi SDK chưa init xong.
 - Overlay: chuỗi phím âm lượng tăng, tăng, giảm, tăng, tăng (`DBG/detect/ActionChangeReceiver.kt:30-40`) hoặc `Ads.openDBBridge(context)` (`SA/api/Ads.kt:287`).
-- Muốn chạy lặp lại có kịch bản thì dùng `super-ads-adb-test`.
+- Muốn chạy lặp lại có kịch bản thì dùng [super-ads-adb-test](../super-ads-adb-test/SKILL.md).
 
 **Verify:** có ít nhất một dòng log hoặc event gắn với placement đang lỗi. Không có thì quay lại Phase 1.
 
-## Phase 3: Phân loại
+### Phase 3: Phân loại
 1. Tìm dòng đầu tiên báo lỗi cho placement (`AdSFl … THẤT BẠI`, `RuleMg Block`, `ProviderTracker load thất bại`…). Định dạng lỗi: `TênLỗi -> [code = N, …]` (`SA/domain/error/AdError.kt:17`).
 2. Tra [error-codes.md](references/error-codes.md) để biết nhóm và ý nghĩa.
 3. Không có mã lỗi: đi theo [symptom-playbook.md](references/symptom-playbook.md).
 
 **Verify:** viết được một câu theo dạng "placement X, lần show lúc T: <bằng chứng> → <nhóm>/<mã> → <nguyên nhân>".
 
-## Phase 4: Sửa
+### Phase 4: Sửa
 | Nguyên nhân | Cách sửa |
 |---|---|
 | Config (placement, priority, key) | MCP `super-ads`: `read_working_config` → `validate_config` → `impact_of_patch` → `apply_patch` → `sync_to_source` (`tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`). `impact_of_patch` trả `mustAsk=true` thì dừng, hỏi user nguyên văn từng `askReasons`; `mustAsk=false` vẫn phải được user duyệt đúng patch đó. Trước `sync_to_source`: kiểm `defaultSyncPath` (trong kết quả `read_working_config`) đúng là file config app nạp, nếu không thì truyền `targetPath` (mặc định có thể là `app/src/main/assets/tmp-*.json`, app không nạp file này). Hỏi user trước khi đổi tần suất hay giới hạn |
@@ -92,12 +87,46 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `
 
 **Verify:** tái hiện đúng thao tác cũ. Lỗi không còn, và có `adEventSink Impression` (`SA/show/AdEventRouter.kt:67`) hoặc `AdShowEvent.Impression`.
 
-## Anti-patterns
+## 🔧 API Reference
+Bảng tên log (`name`) và nguồn: [logging-setup.md](references/logging-setup.md) mục 4. Nhóm và mã lỗi: [error-codes.md](references/error-codes.md).
+
+## ✅ Best Practices
+- Có bằng chứng (dòng log `SuperAdsSDK`, `AdShowEvent`, snapshot, callback `onAdFailed`) trước mỗi kết luận, và trích nó trong báo cáo.
+- Phân loại lỗi theo `FailCategory` (`SA/api/debug/AdShowEvent.kt:97-127`): **blocked** (POLICY/CONFIG/INIT, SDK chủ động không show) khác **error** (LOAD/RENDER/BEHAVIOR/GMS/PRELOAD).
+- Thống kê và so sánh theo `category + code`, không theo tên lỗi hay tên rule (tên rule có thể bị R8 đổi).
+- Lỗi LOAD ở `onAdFailed` / `AdShowEvent.Failed` thường là 204, mã con nằm trong `message` ([error-codes.md](references/error-codes.md), mục "Cách đọc").
+- Khi đổi key config: dẫn ý nghĩa và hiệu ứng từ file tri thức. `confidence` khác `verified` thì ghi "suy luận".
+- Tái hiện lại sau khi sửa để xác nhận.
+
+## ❌ Anti-patterns
+- Kết luận "SDK hỏng" khi Logcat trống: kiểm logger trước ([logging-setup.md](references/logging-setup.md) mục 1).
+- Coi blocked (vd 101 cooldown, 103 premium) là sự cố network.
+- Sửa config production, `Application`, hay file build khi user chưa đồng ý.
+- Tăng hay giảm `show.timeBetweenMs`, `load.timeoutMs`… theo cảm tính.
 - Grep tag Logcat `ReloadCoord`, `PrioChaiLo`… Đó là `name` trong message, tag luôn là `SuperAdsSDK`.
 - Kết luận theo tên lỗi hay tên rule. Dùng `code` (tên rule trên bản release có thể đã bị R8 đổi).
 - Thêm `try/catch` quanh `Ads.show` để "hết lỗi".
 - Lấy giá trị key từ app khác hoặc từ playbook mà không đối chiếu tri thức key.
 
+## ⚠️ Common Issues
+**Logcat trống, không có dòng `SuperAdsSDK`.**
+Cause: SDK không tự in log ra Logcat; logger chưa bật. Solution: kiểm logger ([logging-setup.md](references/logging-setup.md) mục 1), hoặc lấy file `.logads` (mục 6) vốn không phụ thuộc cờ đó.
+
+**Không lấy được file `.logads`.**
+Cause: bản release, không `run-as`. Solution: dùng Logcat (Phase 2).
+
+**`onAdFailed` báo `204` mà không rõ nguyên nhân.**
+Cause: lỗi LOAD của từng adItem bị gói lại. Solution: đọc mã con trong `message` ([error-codes.md](references/error-codes.md), mục "Cách đọc").
+
+## Files created
+Mặc định skill này không tạo file nào trong app; nó chỉ ghi file log về máy phân tích (`ads.logads`, `ads.log`).
+
+## Files modified
+Mặc định skill này không sửa file nào của app. Chỉ khi user đồng ý ở bước sửa mới có thay đổi: `Application` (bật `Ads.logger.init` ở bản debug), dependency `super-ads-debug` hoặc plugin network, file config qua MCP `super-ads` (patch đã được duyệt), hoặc call site theo `super-ads-add-placement`.
+
+## Verification
+Mỗi phase có dòng **Verify** riêng ở Workflow. Kết luận chỉ hợp lệ khi: có bằng chứng gắn với placement lỗi, đã phân loại theo nhóm và mã, và đã tái hiện lại thao tác cũ sau khi sửa (Phase 4).
+
 ## Checklist
 - [ ] Logger bật, có log init.
 - [ ] Đã xác nhận config đang chạy (`global.version`).
@@ -105,5 +134,26 @@ Viết tắt: `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`, `
 - [ ] Nhóm và mã lỗi đúng theo `error-codes.md`.
 - [ ] Đã tái hiện sau khi sửa.
 
+## 📈 Performance Notes
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+> **Not applicable for this skill.**
+
+## 🔄 Migration Guide
+> **Not applicable for this skill.**
+
 ## Output
 Báo cáo gồm: triệu chứng; bằng chứng (trích log hoặc event); nhóm và mã; nguyên nhân; thay đổi đã làm (file hoặc patch); kết quả tái hiện lại; phần chưa xác minh (vd chưa chạy trên thiết bị thật).
+
+## Examples
+- Câu kết luận mẫu (Phase 3): "placement X, lần show lúc T: <bằng chứng> → <nhóm>/<mã> → <nguyên nhân>".
+- Bảng triệu chứng → bằng chứng → nguyên nhân: [references/symptom-playbook.md](references/symptom-playbook.md).
+
+## 📚 References
+- [super-ads-guide](../super-ads-guide/SKILL.md), [super-ads-upgrade](../super-ads-upgrade/SKILL.md)
+- [super-ads-show-rate](../super-ads-show-rate/SKILL.md), [super-ads-adb-test](../super-ads-adb-test/SKILL.md), [super-ads-debug-override](../super-ads-debug-override/SKILL.md)
+- `MIGRATION.md`, `tools/ai_agent_tools/AI_ADS_PLAYBOOK.md`, `tools/ai_agent_tools/data/ads_key_knowledge.json`
+
+## 🏷️ Tags
+`superads` `debug` `logcat` `logads` `error-code` `diagnose`

package/skills/super-ads-debug/references/logging-setup.md

@@ -148,6 +148,8 @@ awk '$2=="WARN" || $2=="ERROR" || $2=="ERROR_AND_CRASH"' ads.logads
 grep -E "^[0-9:.]+  [A-Z_ ]+  ProviderTracker  " ads.logads
 ```
 
+Đã đóng gói sẵn hai phép lọc trên: [../scripts/filter-logads.sh](../scripts/filter-logads.sh) `ads.logads` (chỉ WARN trở lên) hoặc `ads.logads <name>` (một `name`).
+
 **Giới hạn.**
 - Chỉ ghi log ≥ `LogConfig.minLevel` (mặc định `FLOW` = nhận hết) (`SA/domain/model/log/LogConfig.kt:7-8`).
 - Ghi bất đồng bộ qua hàng đợi 1024 dòng; tràn thì **bỏ dòng cũ nhất**. `isFileRecordingEnabled()` trả `true` không bảo đảm dòng cuối đã xuống đĩa.

package/skills/super-ads-debug/scripts/filter-logads.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Lọc file log `.logads` của SuperAds (định dạng: references/logging-setup.md mục 6).
+#
+# Cách dùng:
+#   filter-logads.sh <file.logads>              # chỉ dòng WARN, ERROR, ERROR_AND_CRASH
+#   filter-logads.sh <file.logads> <name>       # chỉ dòng của một `name`, vd ProviderTracker
+#
+# Cột cách nhau bằng hai dấu cách: `HH:mm:ss.SSS  LEVEL  name  k=v ...`.
+set -euo pipefail
+
+if [ "$#" -lt 1 ] || [ "$#" -gt 2 ] || [ ! -f "$1" ]; then
+  sed -n '2,8p' "$0" | sed 's/^# \{0,1\}//' >&2
+  exit 2
+fi
+
+file=$1
+if [ "$#" -eq 1 ]; then
+  awk '$2=="WARN" || $2=="ERROR" || $2=="ERROR_AND_CRASH"' "$file"
+else
+  grep -E "^[0-9:.]+  [A-Z_ ]+  $2  " "$file" || true
+fi

package/skills/super-ads-debug-override/SKILL.md

@@ -1,117 +1,156 @@
 ---
 schema: 1
 name: super-ads-debug-override
-description: Use when a debug build must run once with a SuperAds config different from its bundled asset (an adb-test scenario, trying a patch before sync) — arm an override by broadcast, relaunch, confirm it is active, run the test, then clear it.
-version: 1.1.0
+description: Use when a debug build must run once with a SuperAds config other than its asset - arm, relaunch, test, clear
+version: 1.2.0
 group: Ads
+superAds: ">=4.0.0 <5.0.0"
 ---
 
 # Chạy bản debug với config khác asset, cho một lần khởi động
 
-App khai module `SuperAdsDebugOverride` bằng `debugImplementation` (app mẫu: `app/build.gradle:81`) thì SDK nạp một file JSON thay config gốc cho **đúng một lần khởi động**, chỉ khi adb đã gửi broadcast `OVERRIDE_ARM`, và **khoá** config suốt lần chạy đó: `Ads.loadFromJson`, remote refresh, `reload` trực tiếp đều bị bỏ qua. Không có broadcast thì app chạy y như thường; bản release không có module. Module này thuộc **bộ nền** của mọi app (cùng `SuperAds`, `SuperAdsInHouse`, `SuperAdsDebug`), luôn khai bằng `debugImplementation`.
-
-| Cần | Tài liệu |
-|---|---|
-| Cài module, cơ chế khoá, các bảng kiểm, giới hạn | [references/hook-implementation.md](references/hook-implementation.md) |
-| Chuẩn bị JSON qua MCP | `super-ads-config` |
-| Kịch bản kiểm, đọc log | `super-ads-adb-test` |
-
-Ví dụ dưới dùng app mẫu: `P=com.android.hd.ads2026`. App khác: thay `P` bằng applicationId của bản debug.
+Arm một file JSON bằng broadcast adb, mở lại app để SDK nạp nó thay config gốc, xác nhận bằng log, chạy test, rồi clear. Config bị **khoá** suốt lần chạy đó.
 
 ## When to use
+
 - Kịch bản `super-ads-adb-test` cần config khác asset (cooldown, reload, tắt placement…).
 - Thử một patch trên máy trước khi `sync_to_source`.
 
-## When NOT to use
+## 🚫 When NOT to use
+
 - Bản release: không có receiver, broadcast không tới đâu.
 - App chưa khai module: Stop, chỉ dẫn user theo [hook-implementation.md](references/hook-implementation.md) và hỏi trước khi thêm dòng `debugImplementation` (thêm dependency).
-- Muốn đổi config thật của app → `super-ads-config`.
+- Muốn đổi config thật của app → [super-ads-config](../super-ads-config/SKILL.md).
 
-## Contract
-**MUST**
-- Bật **chỉ** bằng broadcast `OVERRIDE_ARM`. File armed chỉ do receiver ghi.
-- Mỗi lần khởi động muốn dùng override phải ARM lại: lần khởi động lạnh đầu tiên tiêu thụ và xoá file armed (JSON còn, không cần push lại nếu không đổi). Process còn sống sau ARM (receiver vừa khởi động nó) thì mở app sẽ dùng lại process đó, không tiêu thụ ⇒ luôn `force-stop` trước khi mở.
-- Log có **hai nguồn**, đọc đúng nguồn: dòng của module (tag `SuperAdsOverride`: `ARMED`, `ĐANG DÙNG`, `Bỏ override`) dùng `android.util.Log` ⇒ **chỉ có ở Logcat** (`super-ads-debug-override/src/main/java/com/android/fullhd/super_ads/debugoverride/DebugConfigOverride.kt:86`). Dòng của core (`CONFIG OVERRIDE (debug) đang dùng`, `config đang khoá … → bỏ qua`) đi qua `SdkLog` ⇒ có ở file **`.logads`** (`super-ads/src/main/java/com/android/fullhd/super_ads/runtime/SdkRuntime.kt:381`; cách lấy và lọc: [logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 6).
-- Xác nhận override có hiệu lực bằng log, không bằng cảm giác:
-  - `ARMED fileSha256=<x>` khớp `sha256sum` của file đã push;
-  - sau khi mở lại: `CONFIG OVERRIDE ĐANG DÙNG — config khoá · fingerprint=<f>` (tag `SuperAdsOverride`) với `<f>` khớp `fingerprint` lúc ARM, và log core `CONFIG OVERRIDE (debug) đang dùng — config khoá`;
-  - `ConfigUpdate` (trong `.logads`) mang `version=<global.version của override>` và `fingerprint` khớp lúc ARM.
-- Xong việc: `OVERRIDE_CLEAR`, mở lại app, xác nhận không còn log `SuperAdsOverride` và đã về asset.
-- Ghi vào báo cáo: kết quả nào chạy với override (fingerprint, `global.version`).
+## 📋 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.
+- App khai module `SuperAdsDebugOverride` bằng `debugImplementation` (app mẫu: `app/build.gradle:81`). Module này thuộc **bộ nền** của mọi app (cùng `SuperAds`, `SuperAdsInHouse`, `SuperAdsDebug`).
+- Bản đang cài là bản debug (debuggable), nếu không ARM trả `REJECTED:not_debuggable`.
+- JSON đã qua `validate_config` (chuẩn bị bằng [super-ads-config](../super-ads-config/SKILL.md)).
+- Máy không bị phiên / workflow khác dùng cùng app.
+- Ví dụ dùng app mẫu: `P=com.android.hd.ads2026`. App khác: thay `P` bằng applicationId của bản debug.
+
+## ⚡ Quick Reference
+
+| Cần | Mở |
+|---|---|
+| Cài module, cơ chế khoá, bảng kiểm, giới hạn | [references/hook-implementation.md](references/hook-implementation.md) |
+| Kiểm module có trong merged manifest | [snippets/check-module.md](snippets/check-module.md) |
+| Push JSON và ARM | [snippets/arm-override.md](snippets/arm-override.md) |
+| Mở lại, xác nhận bằng log | [snippets/confirm-active.md](snippets/confirm-active.md) |
+| Dọn, về asset | [snippets/clear-override.md](snippets/clear-override.md) |
+| Chuẩn bị JSON qua MCP | [super-ads-config](../super-ads-config/SKILL.md) |
+| Kịch bản kiểm, đọc log | [super-ads-adb-test](../super-ads-adb-test/SKILL.md) |
 
-**MUST NOT**
-- Không tự ghi file `superads_override.armed` bằng tay (kể cả để "tiết kiệm bước").
-- Không coi log `config đang khoá (override debug) → bỏ qua …` là lỗi của app: đó là SDK chặn đúng một lần ghi đè. Ghi vào báo cáo cổng nào bị chặn (kết quả phụ thuộc lời gọi đó thì không đại diện cho production).
-- Không dùng override khi máy đang có phiên khác thao tác cùng app (force-stop của bạn sẽ chen vào, và app của họ sẽ chạy config của bạn).
-- Không push JSON chưa qua `validate_config`.
+## 🏗️ Recommended Architecture
+
+Module `SuperAdsDebugOverride` nạp một file JSON thay config gốc cho **đúng một lần khởi động**, chỉ khi adb đã gửi broadcast `OVERRIDE_ARM`, và **khoá** config suốt lần chạy đó: `Ads.loadFromJson`, remote refresh, `reload` trực tiếp đều bị bỏ qua. Không có broadcast thì app chạy y như thường; bản release không có module. Luôn khai bằng `debugImplementation`. Cơ chế và các cổng bị khoá: [hook-implementation.md](references/hook-implementation.md).
+
+## Workflow
+
+### Stop conditions (dừng và hỏi user)
 
-## Stop conditions (dừng và hỏi user)
 - Merged manifest bản debug không có `ConfigOverrideReceiver`.
 - `am broadcast` trả `result=0` mà **không** có `data=` (receiver không chạy), hoặc `REJECTED:<lý do>`. Bảng lý do: [hook-implementation.md](references/hook-implementation.md).
 - Sau khi mở lại có `Bỏ override, dùng config gốc: <lý do>` thay vì `ĐANG DÙNG`.
 - Có `ĐANG DÙNG` nhưng thiếu log khoá của core, hoặc `ConfigUpdate` không mang version/fingerprint của override.
 - Máy đang bị tiến trình / workflow khác dùng.
 
-## Phase 1: Kiểm module
-```bash
-./gradlew :app:processDebugManifest
-grep -c 'debugoverride.ConfigOverrideReceiver' app/build/intermediates/merged_manifests/debug/processDebugManifest/AndroidManifest.xml
-```
-**Verify:** kết quả ≥ 1. Bằng 0 ⇒ Stop. Bản đang cài phải là bản debug (debuggable); không thì ARM trả `REJECTED:not_debuggable`.
+### 1. Kiểm module
+
+Chạy [snippets/check-module.md](snippets/check-module.md). Bản đang cài phải là bản debug (debuggable); không thì ARM trả `REJECTED:not_debuggable`.
+
+### 2. Chuẩn bị JSON
 
-## Phase 2: Chuẩn bị JSON
-1. `read_working_config` → lấy `config` (production projection), hoặc soạn qua `super-ads-config` (đến bước `validate_config`, **chưa** `sync_to_source`).
+1. `read_working_config` → lấy `config` (production projection), hoặc soạn qua [super-ads-config](../super-ads-config/SKILL.md) (đến bước `validate_config`, **chưa** `sync_to_source`).
 2. `validate_config {config}` không có error. Đặt `global.version` dễ nhận (vd `override-s1`).
 3. Ghi ra file cục bộ, `sha256sum <file>`.
 
-**Verify:** có file, sha256, `global.version`.
-
-## Phase 3: Push và ARM
-```bash
-adb push cfg.json /data/local/tmp/ovr.json
-adb shell "run-as $P sh -c 'cp /data/local/tmp/ovr.json files/superads_override.json'"
-adb shell am broadcast -n $P/com.android.fullhd.super_ads.debugoverride.ConfigOverrideReceiver -a $P.OVERRIDE_ARM
-```
-**Verify:** dòng cuối `Broadcast completed: result=0, data="ARMED fileSha256=<sha> fingerprint=<f> version=<v>"`, `<sha>` khớp Phase 2. Broadcast tới được cả khi app đang force-stop (đã kiểm trên Pixel 5).
-
-## Phase 4: Mở lại, xác nhận
-```bash
-adb logcat -c
-adb shell am force-stop $P
-adb shell am start -n $P/.MainActivity
-sleep 5
-# Logcat: log của module override
-adb logcat -d -s SuperAdsOverride:V
-# .logads: log của core (file mới nhất = lần chạy vừa mở)
-F=$(adb shell run-as $P ls -t cache/logads | head -1 | tr -d '\r')
-adb exec-out run-as $P cat cache/logads/$F > ovr.logads
-grep -E 'CONFIG OVERRIDE|config đang khoá|ConfigUpdate' ovr.logads
-```
-Hạn ARM: 10 phút (`super-ads-debug-override/src/main/java/com/android/fullhd/super_ads/debugoverride/DebugConfigOverride.kt:31`). `.logads` cần bản debuggable với `isDebug = true` (tự bật ghi file) hoặc đã bật switch "Record Log To File"; không lấy được file thì đọc bằng Logcat: `adb logcat -d | grep -E 'SuperAdsOverride|CONFIG OVERRIDE|ConfigUpdate'` (cần bật log SDK).
-
-**Verify:** Logcat có `CONFIG OVERRIDE ĐANG DÙNG — config khoá · fingerprint=<f>`; `ovr.logads` có `CONFIG OVERRIDE (debug) đang dùng` và dòng `ConfigUpdate` với `version=<global.version của override>` và `fingerprint` **trùng** `fingerprint` lúc ARM (SDK ghi dòng này mỗi lần nạp config).
-
-## Phase 5: Chạy test
-Theo `super-ads-adb-test`. Không force-stop / mở lại app giữa chừng: lần mở sau đã về asset.
-
-Lấy log kịch bản bằng `.logads` của lần chạy này (cùng cách Phase 4); app không bị khởi động lại nên vẫn là một file.
-
-**Verify:** ghi lại mọi dòng `config đang khoá (override debug) → bỏ qua …` trong `.logads` (cổng nào đã bị chặn).
-
-## Phase 6: Dọn
-```bash
-adb shell am broadcast -n $P/com.android.fullhd.super_ads.debugoverride.ConfigOverrideReceiver -a $P.OVERRIDE_CLEAR
-adb shell am force-stop $P
-adb shell am start -n $P/.MainActivity
-```
-**Verify:** `data="CLEARED"`; `adb shell run-as $P ls files` không còn `superads_override.*`; mở lại: Logcat không có `SuperAdsOverride`, `.logads` mới không có `CONFIG OVERRIDE`, `ConfigUpdate` về version của asset.
-
-## Anti-patterns
+### 3. Push và ARM
+
+Chạy [snippets/arm-override.md](snippets/arm-override.md). Broadcast tới được cả khi app đang force-stop (đã kiểm trên Pixel 5).
+
+### 4. Mở lại, xác nhận
+
+Chạy [snippets/confirm-active.md](snippets/confirm-active.md). Hạn ARM: 10 phút (`super-ads-debug-override/src/main/java/com/android/fullhd/super_ads/debugoverride/DebugConfigOverride.kt:31`). `.logads` cần bản debuggable với `isDebug = true` (tự bật ghi file) hoặc đã bật switch "Record Log To File"; không lấy được file thì đọc bằng Logcat: `adb logcat -d | grep -E 'SuperAdsOverride|CONFIG OVERRIDE|ConfigUpdate'` (cần bật log SDK).
+
+### 5. Chạy test
+
+Theo [super-ads-adb-test](../super-ads-adb-test/SKILL.md). Không force-stop / mở lại app giữa chừng: lần mở sau đã về asset.
+
+Lấy log kịch bản bằng `.logads` của lần chạy này (cùng cách Bước 4); app không bị khởi động lại nên vẫn là một file.
+
+### 6. Dọn
+
+Chạy [snippets/clear-override.md](snippets/clear-override.md).
+
+## 🔧 API Reference
+
+| Hành động | Lệnh / dấu hiệu | Kết quả mong đợi |
+|---|---|---|
+| ARM | `am broadcast -a $P.OVERRIDE_ARM` tới `ConfigOverrideReceiver` | `data="ARMED fileSha256=<sha> fingerprint=<f> version=<v>"` |
+| CLEAR | `am broadcast -a $P.OVERRIDE_CLEAR` tới `ConfigOverrideReceiver` | `data="CLEARED"` |
+| Từ chối | ARM không hợp lệ | `REJECTED:<lý do>`; bảng lý do trong [hook-implementation.md](references/hook-implementation.md) |
+| Log module (tag `SuperAdsOverride`) | `ARMED`, `ĐANG DÙNG`, `Bỏ override` | Chỉ ở Logcat |
+| Log core | `CONFIG OVERRIDE (debug) đang dùng`, `config đang khoá … → bỏ qua`, `ConfigUpdate` | Ở file `.logads` |
+
+## ✅ Best Practices
+
+- Bật **chỉ** bằng broadcast `OVERRIDE_ARM`. File armed chỉ do receiver ghi.
+- Mỗi lần khởi động muốn dùng override phải ARM lại: lần khởi động lạnh đầu tiên tiêu thụ và xoá file armed (JSON còn, không cần push lại nếu không đổi). Process còn sống sau ARM (receiver vừa khởi động nó) thì mở app sẽ dùng lại process đó, không tiêu thụ ⇒ luôn `force-stop` trước khi mở.
+- Log có **hai nguồn**, đọc đúng nguồn: dòng của module (tag `SuperAdsOverride`: `ARMED`, `ĐANG DÙNG`, `Bỏ override`) dùng `android.util.Log` ⇒ **chỉ có ở Logcat** (`super-ads-debug-override/src/main/java/com/android/fullhd/super_ads/debugoverride/DebugConfigOverride.kt:86`). Dòng của core (`CONFIG OVERRIDE (debug) đang dùng`, `config đang khoá … → bỏ qua`) đi qua `SdkLog` ⇒ có ở file **`.logads`** (`super-ads/src/main/java/com/android/fullhd/super_ads/runtime/SdkRuntime.kt:381`; cách lấy và lọc: [logging-setup.md](../super-ads-debug/references/logging-setup.md) mục 6).
+- Xác nhận override có hiệu lực bằng log, không bằng cảm giác:
+  - `ARMED fileSha256=<x>` khớp `sha256sum` của file đã push;
+  - sau khi mở lại: `CONFIG OVERRIDE ĐANG DÙNG — config khoá · fingerprint=<f>` (tag `SuperAdsOverride`) với `<f>` khớp `fingerprint` lúc ARM, và log core `CONFIG OVERRIDE (debug) đang dùng — config khoá`;
+  - `ConfigUpdate` (trong `.logads`) mang `version=<global.version của override>` và `fingerprint` khớp lúc ARM.
+- Xong việc: `OVERRIDE_CLEAR`, mở lại app, xác nhận không còn log `SuperAdsOverride` và đã về asset.
+- Ghi vào báo cáo: kết quả nào chạy với override (fingerprint, `global.version`).
+
+## ❌ Anti-patterns
+
+- Tự ghi file `superads_override.armed` bằng tay (kể cả để "tiết kiệm bước").
+- Coi log `config đang khoá (override debug) → bỏ qua …` là lỗi của app: đó là SDK chặn đúng một lần ghi đè. Ghi vào báo cáo cổng nào bị chặn (kết quả phụ thuộc lời gọi đó thì không đại diện cho production).
+- Dùng override khi máy đang có phiên khác thao tác cùng app (force-stop của bạn sẽ chen vào, và app của họ sẽ chạy config của bạn).
+- Push JSON chưa qua `validate_config`.
 - ARM một lần rồi chạy nhiều kịch bản có force-stop ở giữa, tưởng vẫn dùng override.
 - So sha256 của file với `fingerprint`: hai giá trị khác nhau (fingerprint tính trên JSON SDK serialize lại).
 - Dùng override để "sửa" config cho người khác test.
 
+## ⚠️ Common Issues
+
+**`am broadcast` trả `result=0` mà không có `data=`.**
+Cause: receiver không chạy. Solution: Stop; kiểm merged manifest (Bước 1) rồi hỏi user.
+
+**`REJECTED:<lý do>`.**
+Cause: JSON hoặc app không đạt kiểm lúc ARM (ví dụ `not_debuggable`, `missing_json`, `json_blank`, `json_invalid:*`, `sdk_rejected`). Solution: sửa theo bảng trong [hook-implementation.md](references/hook-implementation.md), ARM lại.
+
+**Mở lại thấy `Bỏ override, dùng config gốc: <lý do>` thay vì `ĐANG DÙNG`.**
+Cause: `consume` từ chối (armed hỏng / hết hạn, thiếu JSON, JSON đổi sau ARM…). Solution: Stop; bảng `consume` trong [hook-implementation.md](references/hook-implementation.md), ARM lại.
+
+## Files created
+
+- Trên máy dev: JSON override cục bộ (`cfg.json`), `ovr.logads` (log lần chạy).
+- Trên thiết bị (trong `files/` của app): `superads_override.json` (do bạn push) và `superads_override.armed` (chỉ receiver ghi). `OVERRIDE_CLEAR` xoá cả hai.
+
+## Files modified
+
+- Không sửa file nào của repo app. Ngoại lệ: dòng `debugImplementation` khi app chưa khai module, và chỉ sau khi user đồng ý (thêm dependency, xem [hook-implementation.md](references/hook-implementation.md)).
+
+## Verification
+
+Báo output thật. Sau mỗi bước ở Workflow:
+
+1. **Kiểm module:** kết quả ≥ 1. Bằng 0 ⇒ Stop.
+2. **Chuẩn bị JSON:** có file, sha256, `global.version`.
+3. **Push và ARM:** dòng cuối `Broadcast completed: result=0, data="ARMED fileSha256=<sha> fingerprint=<f> version=<v>"`, `<sha>` khớp Bước 2.
+4. **Mở lại, xác nhận:** Logcat có `CONFIG OVERRIDE ĐANG DÙNG — config khoá · fingerprint=<f>`; `ovr.logads` có `CONFIG OVERRIDE (debug) đang dùng` và dòng `ConfigUpdate` với `version=<global.version của override>` và `fingerprint` **trùng** `fingerprint` lúc ARM (SDK ghi dòng này mỗi lần nạp config).
+5. **Chạy test:** ghi lại mọi dòng `config đang khoá (override debug) → bỏ qua …` trong `.logads` (cổng nào đã bị chặn).
+6. **Dọn:** `data="CLEARED"`; `adb shell run-as $P ls files` không còn `superads_override.*`; mở lại: Logcat không có `SuperAdsOverride`, `.logads` mới không có `CONFIG OVERRIDE`, `ConfigUpdate` về version của asset.
+
 ## Checklist
+
 - [ ] Receiver của module có trong merged manifest debug.
 - [ ] JSON qua `validate_config`, có sha256 và `global.version`.
 - [ ] `ARMED`, sha khớp.
@@ -119,5 +158,39 @@ adb shell am start -n $P/.MainActivity
 - [ ] Test xong, đã ghi các cổng bị chặn (nếu có).
 - [ ] `CLEARED`, đã về asset.
 
+## 📈 Performance Notes
+
+> **Not applicable for this skill.**
+
+## 🔒 Security Notes
+
+- Receiver `ConfigOverrideReceiver` được export để adb shell gửi được và không đòi permission; vì vậy module **chỉ** khai bằng `debugImplementation`. Bản release không có provider, receiver, class nào của module ([hook-implementation.md](references/hook-implementation.md)).
+- App không debuggable: ARM trả `REJECTED:not_debuggable`, installer không cài override.
+- Không dùng override khi máy đang có phiên khác thao tác cùng app.
+
+## 🔄 Migration Guide
+
+> **Not applicable for this skill.**
+
 ## Output
+
 JSON đã dùng (đường dẫn, sha256, fingerprint, `global.version`), log ARM / ACTIVE / CLEAR nguyên văn, kết quả test, phần chưa xác minh.
+
+## Examples
+
+- Push và ARM: [snippets/arm-override.md](snippets/arm-override.md)
+- Mở lại, xác nhận: [snippets/confirm-active.md](snippets/confirm-active.md)
+- Dọn: [snippets/clear-override.md](snippets/clear-override.md)
+- Các ca đã kiểm trên Pixel 5 (mở bình thường, ARM, từ chối, CLEAR, release): [references/hook-implementation.md](references/hook-implementation.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-config](../super-ads-config/SKILL.md), [super-ads-adb-test](../super-ads-adb-test/SKILL.md), [super-ads-debug](../super-ads-debug/SKILL.md).
+- Log và `.logads`: [logging-setup.md](../super-ads-debug/references/logging-setup.md).
+- Repo SDK: `MIGRATION.md`.
+
+## 🏷️ Tags
+
+`superads`, `debug`, `override`, `adb`, `broadcast`, `config`

package/skills/super-ads-debug-override/snippets/arm-override.md

@@ -0,0 +1,9 @@
+# Push JSON và ARM
+
+> `P` = applicationId của bản debug (app mẫu: `P=com.android.hd.ads2026`). Đặt biến này trước khi chạy.
+
+```bash
+adb push cfg.json /data/local/tmp/ovr.json
+adb shell "run-as $P sh -c 'cp /data/local/tmp/ovr.json files/superads_override.json'"
+adb shell am broadcast -n $P/com.android.fullhd.super_ads.debugoverride.ConfigOverrideReceiver -a $P.OVERRIDE_ARM
+```

package/skills/super-ads-debug-override/snippets/check-module.md

@@ -0,0 +1,8 @@
+# Kiểm module có trong merged manifest debug
+
+> `P` = applicationId của bản debug (app mẫu: `P=com.android.hd.ads2026`). Đặt biến này trước khi chạy.
+
+```bash
+./gradlew :app:processDebugManifest
+grep -c 'debugoverride.ConfigOverrideReceiver' app/build/intermediates/merged_manifests/debug/processDebugManifest/AndroidManifest.xml
+```

package/skills/super-ads-debug-override/snippets/clear-override.md

@@ -0,0 +1,9 @@
+# Dọn override và về asset
+
+> `P` = applicationId của bản debug (app mẫu: `P=com.android.hd.ads2026`). Đặt biến này trước khi chạy.
+
+```bash
+adb shell am broadcast -n $P/com.android.fullhd.super_ads.debugoverride.ConfigOverrideReceiver -a $P.OVERRIDE_CLEAR
+adb shell am force-stop $P
+adb shell am start -n $P/.MainActivity
+```

package/skills/super-ads-debug-override/snippets/confirm-active.md

@@ -0,0 +1,16 @@
+# Mở lại app và xác nhận override đang dùng
+
+> `P` = applicationId của bản debug (app mẫu: `P=com.android.hd.ads2026`). Đặt biến này trước khi chạy.
+
+```bash
+adb logcat -c
+adb shell am force-stop $P
+adb shell am start -n $P/.MainActivity
+sleep 5
+# Logcat: log của module override
+adb logcat -d -s SuperAdsOverride:V
+# .logads: log của core (file mới nhất = lần chạy vừa mở)
+F=$(adb shell run-as $P ls -t cache/logads | head -1 | tr -d '\r')
+adb exec-out run-as $P cat cache/logads/$F > ovr.logads
+grep -E 'CONFIG OVERRIDE|config đang khoá|ConfigUpdate' ovr.logads
+```