Replace the Apple-vs-Adapty install gap with a standard metric set

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-ads",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Run and audit Apple Ads from your agent — cohort bid reviews, Market Intelligence keyword opportunities, search-term harvesting, negatives, CPP routing, and read-only account diagnostics through the Adapty CLI.",
   "author": { "name": "Adapty", "email": "support@adapty.io" },
   "homepage": "https://adapty.io/docs/developer-cli-ads-manager-skill",

README.md

@@ -73,7 +73,7 @@ Settings → Capabilities → enable code execution → allow network egress →
 | | |
 |---|---|
 | **`apple-ads`** | The operator. Reads performance, changes bids and budgets, adds keywords and negatives, harvests search terms, launches and pauses campaigns — all through the CLI, with confirmation before anything that spends money. |
-| **`apple-ads-audit`** | The read-only auditor. Checks account health, serving, live structure, traffic ownership, duplicate Exact keywords, and a simple same-window Apple-versus-Adapty install comparison. It never writes. |
+| **`apple-ads-audit`** | The read-only auditor. Checks account health, serving, live structure, traffic ownership, duplicate Exact keywords, and a performance snapshot — spend, impressions, taps, avg CPT, installs, CPI, cost per trial and cost per paid. It never writes. |
 | **`apple-ads-strategy`** | The planner. **Needs no account, no CLI, no subscription.** Turns "I have a TV remote app, where do I start" into a full account structure, keyword taxonomy, starting budget and negative list. |
 | **Playbooks** | Weekly check-in · account health · structure audit · cohort ROAS · keyword bid review · Market Intelligence keyword opportunities · search-term harvesting · negative keyword mining · CPP routing · budget reallocation · campaign launch · runaway spend · automation rules. |
 | **Vertical guides** | Category-specific playbooks — demand profile, keyword taxonomy, account structure, starting economics and the failure modes specific to that category. |

README.tr.md

@@ -1,4 +1,4 @@
-<!-- i18n-source: README.md  i18n-hash: 7c1ea480b94019ca  -->
+<!-- i18n-source: README.md  i18n-hash: 0d1ee2588d9c2cc3  -->
 
 [English](README.md) · [简体中文](README.zh-CN.md) · **Türkçe**
 
@@ -73,7 +73,7 @@ Ayarlar → Capabilities → kod çalıştırmayı etkinleştirin → ağ çık
 | | |
 |---|---|
 | **`apple-ads`** | Uygulayıcı. Performansı okur, teklifleri ve bütçeleri değiştirir, anahtar kelime ve negatif ekler, arama terimlerini hasat eder, kampanyaları başlatır ve durdurur — hepsi CLI üzerinden ve para harcayan her işlemden önce onay alarak. |
-| **`apple-ads-audit`** | Salt okunur denetçi. Hesap sağlığını, yayın durumunu, canlı yapıyı, trafik sahipliğini, yinelenen tam eşleşmeli anahtar kelimeleri ve aynı tarih aralığında Apple ile Adapty kurulumlarının basit karşılaştırmasını kontrol eder. Hiçbir şeyi değiştirmez. |
+| **`apple-ads-audit`** | Salt okunur denetçi. Hesap sağlığını, yayın durumunu, canlı yapıyı, trafik sahipliğini, yinelenen tam eşleşmeli anahtar kelimeleri ve bir performans özetini — harcama, gösterim, dokunma, ortalama CPT, yükleme, CPI, deneme başına maliyet ve ödeme başına maliyet — kontrol eder. Hiçbir şeyi değiştirmez. |
 | **`apple-ads-strategy`** | Planlayıcı. **Hesap, CLI veya abonelik gerektirmez.** "Bir TV kumandası uygulamam var, nereden başlamalıyım" sorusunu eksiksiz bir hesap yapısına, anahtar kelime taksonomisine, başlangıç bütçesine ve negatif listesine dönüştürür. |
 | **Oyun kitapları** | Haftalık kontrol · hesap sağlığı · yapı denetimi · kohort ROAS · anahtar kelime teklif incelemesi · Market Intelligence fırsatları · arama terimi hasadı · negatif anahtar kelime madenciliği · CPP yönlendirme · bütçe yeniden dağıtımı · kampanya başlatma · kontrolsüz harcama · otomasyon kuralları. |
 | **Dikey rehberler** | Kategoriye özel oyun kitapları — talep profili, anahtar kelime taksonomisi, hesap yapısı, başlangıç ekonomisi ve o kategoriye özgü başarısızlık biçimleri. |

README.zh-CN.md

@@ -1,4 +1,4 @@
-<!-- i18n-source: README.md  i18n-hash: 7c1ea480b94019ca  -->
+<!-- i18n-source: README.md  i18n-hash: 0d1ee2588d9c2cc3  -->
 
 [English](README.md) · **简体中文** · [Türkçe](README.tr.md)
 
@@ -73,7 +73,7 @@ Cowork 在沙箱中执行命令，只能访问白名单域名。安装前请**
 | | |
 |---|---|
 | **`apple-ads`** | 执行层。读取投放表现、调整出价与预算、添加关键词与否定词、收割搜索词、启动与暂停广告系列 —— 全部通过 CLI 完成，任何花钱的操作前都会先确认。 |
-| **`apple-ads-audit`** | 只读审计层。检查账户健康、投放状态、线上结构、流量归属、重复的精确匹配关键词，并在同一时间范围内简单比较 Apple 与 Adapty 的安装量。绝不执行写操作。 |
+| **`apple-ads-audit`** | 只读审计层。检查账户健康、投放状态、线上结构、流量归属、重复的精确匹配关键词，并给出一份性能快照——花费、展示、点击、平均 CPT、安装量、CPI、单次试用成本和单次付费成本。绝不执行写操作。 |
 | **`apple-ads-strategy`** | 规划层。**不需要账号、不需要 CLI、不需要订阅。** 把「我有一个电视遥控器 App，该从哪儿开始」变成完整的账户结构、关键词分类、启动预算和否定词清单。 |
 | **操作手册** | 每周检查 · 账户健康 · 结构审计 · 同期群 ROAS · 关键词出价审查 · Market Intelligence 关键词机会 · 搜索词收割 · 否定关键词挖掘 · CPP 路由 · 预算再分配 · 广告系列启动 · 超支应急 · 自动化规则。 |
 | **垂类指南** | 分品类的操作手册 —— 需求画像、关键词分类、账户结构、启动期经济模型，以及该品类特有的失败模式。 |

commands/asa-audit.md

@@ -4,8 +4,8 @@ description: Read-only Apple Ads account health or live structure audit
 
 Audit my connected Apple Ads account without changing anything.
 
-Use the `apple-ads-audit` skill and run its preflight. Route a broad health, serving, performance,
-or Apple-versus-Adapty installs question to `references/playbooks/account-health.md`. Route live
+Use the `apple-ads-audit` skill and run its preflight. Route a broad health, serving, or performance
+question to `references/playbooks/account-health.md`. Route live
 structure, duplicate Exact ownership, or missing cross-negatives to
 `references/playbooks/structure-audit.md`. Read one primary playbook, return evidence and
 confidence, and stop before every mutation.

commands/asa-review.md

@@ -1,22 +1,27 @@
 ---
-description: Weekly Apple Ads check-in — direction, install comparison, outliers, and one action
+description: Weekly Apple Ads check-in — the standard metric set, outliers, and one action
 ---
 
 Run the weekly check-in for my Apple Ads account.
 
 Use the `apple-ads` skill. Start with `references/playbooks/preflight.md`, then follow
 `references/playbooks/weekly-review.md` exactly — including its call budget. Ask me for the date
-range if I did not give one and whether I want a comparison. If I did not name a success metric,
-offer these choices in this exact order:
+range if I did not give one and whether I want a comparison. Ask whether the app offers a free trial
+before you offer a success metric. If I did not name a success metric, offer these choices in this
+exact order:
 
 1. Cost per paid
 2. Cost per trial
 3. Net ROAS at day X
 
-Ask for my numeric target or guardrail after the metric is selected. Always use net values for
-revenue-family metrics; never offer gross or proceeds. Ask for a cohort day only when the selected
-metric is `revenue`, `roas`, `arpu`, `arppu`, `arpas`, or `roi`. Never ask for a cohort window, pass
-`--by-days` / `--order-by-day`, or label a result `day-X` for `cost_per_paid`, `cost_per_trial`, or
-any other non-cohort metric. Include the same-window Apple total installs versus Adapty installs
-comparison, up to two positive changes, up to two concerns, and one primary action. Do not
-investigate attribution and do not write.
+Skip choice 2 when I said the app has no free trial. Ask for my numeric target or guardrail after the
+metric is selected. Always use net values for revenue-family metrics; never offer gross or proceeds.
+Ask for a cohort day only when the selected metric is `revenue`, `roas`, `arpu`, `arppu`, `arpas`, or
+`roi`. Never ask for a cohort window, pass `--by-days` / `--order-by-day`, or label a result `day-X`
+for `cost_per_paid`, `cost_per_trial`, or any other non-cohort metric.
+
+Report the playbook's standard metric set for the requested window — `spend`, `impressions`, `taps`,
+`avg_cpt`, `total_installs`, `total_avg_cpi`, `cost_per_trial` when the app has a trial, and
+`cost_per_paid` — with the prior value and signed delta per row when I asked for a comparison. Then
+give up to two positive changes, up to two concerns, and one primary action. Do not investigate
+attribution and do not write.

docs/IMPROVEMENT-IDEAS.md

@@ -40,8 +40,8 @@ Minimum case set:
 - one successful case for each of the eight flagship workflows;
 - one insufficient-data case for each workflow;
 - audit versus operator versus strategy routing conflicts;
-- Apple installs equal to zero;
-- missing Adapty installs;
+- a metric missing from a `metrics overview` response;
+- `cost_per_trial` requested for an app with no free trial;
 - Market Intelligence response without `byApps`;
 - more than five competitor App Store ids;
 - an opportunity already present as an active keyword;
@@ -298,6 +298,7 @@ Do not add these until a concrete product need changes the decision:
 
 - more top-level skills;
 - a Maximize readiness workflow;
+- any comparison between Apple install counts and Adapty install counts;
 - deep attribution reconciliation;
 - a universal account health score;
 - universal CPA, ROAS, or bid-change percentages;

docs/playbooks/README.md

@@ -10,7 +10,7 @@ The authoritative copies live under `skills/`, and these are generated from them
 | Account health | what needs attention in a live account, without changing it | [`account-health.md`](../../skills/apple-ads-audit/references/playbooks/account-health.md) |
 | Structure audit | duplicate ownership, cross-negatives and live hierarchy conflicts | [`structure-audit.md`](../../skills/apple-ads-audit/references/playbooks/structure-audit.md) |
 | Cohort ROAS | which keywords actually pay back, by renewal window | [`cohort-roas.md`](../../skills/apple-ads/references/playbooks/cohort-roas.md) |
-| Weekly check-in | direction, install comparison, outliers and one action in at most four analytics calls | [`weekly-review.md`](../../skills/apple-ads/references/playbooks/weekly-review.md) |
+| Weekly check-in | direction on the standard metric set, outliers and one action in at most four analytics calls | [`weekly-review.md`](../../skills/apple-ads/references/playbooks/weekly-review.md) |
 | Keyword opportunities | per-app, per-country competitor terms from Market Intelligence | [`keyword-opportunity.md`](../../skills/apple-ads/references/playbooks/keyword-opportunity.md) |
 | Keyword bid review | evidence-based bid changes with cohort maturity gates | [`bid-optimization.md`](../../skills/apple-ads/references/playbooks/bid-optimization.md) |
 | Search-term harvesting | turn real queries into verified Exact owners and cross-negatives | [`search-term-harvesting.md`](../../skills/apple-ads/references/playbooks/search-term-harvesting.md) |

docs/playbooks/README.tr.md

@@ -10,7 +10,7 @@ Yetkili kopyalar `skills/` altındadır; bu sayfa onlardan üretilir.
 | Hesap sağlığı | canlı bir hesapta hiçbir şeyi değiştirmeden ilgilenilmesi gerekenleri bulma | [`account-health.md`](../../skills/apple-ads-audit/references/playbooks/account-health.md) |
 | Yapı denetimi | yinelenen sahiplik, çapraz negatifler ve canlı hiyerarşi çatışmaları | [`structure-audit.md`](../../skills/apple-ads-audit/references/playbooks/structure-audit.md) |
 | Kohort ROAS | hangi anahtar kelimelerin gerçekten kâr getirdiği, yenileme penceresine göre | [`cohort-roas.md`](../../skills/apple-ads/references/playbooks/cohort-roas.md) |
-| Haftalık kontrol | en fazla dört analiz çağrısıyla yön, kurulum karşılaştırması, aykırı değerler ve tek eylem | [`weekly-review.md`](../../skills/apple-ads/references/playbooks/weekly-review.md) |
+| Haftalık kontrol | en fazla dört analiz çağrısıyla standart metrik setinde yön, aykırı değerler ve tek eylem | [`weekly-review.md`](../../skills/apple-ads/references/playbooks/weekly-review.md) |
 | Anahtar kelime fırsatları | Market Intelligence'tan uygulama ve ülke bazında rakip terimleri | [`keyword-opportunity.md`](../../skills/apple-ads/references/playbooks/keyword-opportunity.md) |
 | Teklif incelemesi | kohort olgunluk kapılarıyla kanıta dayalı teklif değişiklikleri | [`bid-optimization.md`](../../skills/apple-ads/references/playbooks/bid-optimization.md) |
 | Arama terimi hasadı | gerçek sorguları doğrulanmış tam eşleşme sahiplerine ve çapraz negatiflere dönüştürme | [`search-term-harvesting.md`](../../skills/apple-ads/references/playbooks/search-term-harvesting.md) |

docs/playbooks/README.zh-CN.md

@@ -10,7 +10,7 @@
 | 账户健康 | 在不做任何修改的前提下找出线上账户需要关注的问题 | [`account-health.md`](../../skills/apple-ads-audit/references/playbooks/account-health.md) |
 | 结构审计 | 查找重复归属、交叉否定词和线上层级冲突 | [`structure-audit.md`](../../skills/apple-ads-audit/references/playbooks/structure-audit.md) |
 | 同期群 ROAS | 按续订窗口判断哪些关键词真正回本 | [`cohort-roas.md`](../../skills/apple-ads/references/playbooks/cohort-roas.md) |
-| 每周检查 | 最多四次分析调用，给出趋势、安装量对比、异常项和一个行动 | [`weekly-review.md`](../../skills/apple-ads/references/playbooks/weekly-review.md) |
+| 每周检查 | 最多四次分析调用，基于标准指标集给出趋势、异常项和一个行动 | [`weekly-review.md`](../../skills/apple-ads/references/playbooks/weekly-review.md) |
 | 关键词机会 | 从 Market Intelligence 获取按 App 和国家划分的竞品搜索词 | [`keyword-opportunity.md`](../../skills/apple-ads/references/playbooks/keyword-opportunity.md) |
 | 关键词出价审查 | 通过同期群成熟度门槛提出基于证据的出价调整 | [`bid-optimization.md`](../../skills/apple-ads/references/playbooks/bid-optimization.md) |
 | 搜索词收割 | 把真实查询变成已验证的精确匹配归属和交叉否定词 | [`search-term-harvesting.md`](../../skills/apple-ads/references/playbooks/search-term-harvesting.md) |

examples/prompts.md

@@ -16,7 +16,7 @@ Structure an account for a language-learning app selling annual subscriptions in
 ```
 Audit this live Apple Ads account and show me what needs attention. Do not change anything.
 Which campaigns are confirmed not to be serving, and what evidence explains each one?
-How far apart are Apple total installs and Adapty installs for the same dates? Keep it simple.
+Give me spend, impressions, taps, avg CPT, installs, CPI and cost per paid for last week.
 Are Brand, Competitor, Discovery and Exact traffic separated correctly in this live account?
 Where do active Exact keywords have more than one owner?
 Which Discovery ad groups are missing cross-negatives for verified Exact owners?

scripts/lint-workflows.mjs

@@ -2,7 +2,7 @@
 // Behavioral contracts for the flagship Apple Ads workflows.
 //
 // The playbook linter validates shape and command existence. This file protects the decisions that
-// are easy to weaken accidentally: read-only audit boundaries, simple install comparison, Market
+// are easy to weaken accidentally: read-only audit boundaries, the standard metric set, Market
 // Intelligence detail, and mutation ordering.
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
@@ -71,8 +71,6 @@ if (setupDescription.includes('402') || setupDescription.includes('ads_manager_s
 }
 
 requireText(auditSkill, 'This skill has no write', 'explicit read-only audit boundary')
-requireText(auditSkill, 'relative_gap = absolute_gap / apple_installs', 'install-gap formula')
-requireText(auditSkill, 'only when `apple_installs > 0`', 'zero-denominator guard')
 
 const WRITE_COMMAND = /asa\s+(?:campaigns|ad-groups|ads|keywords|negative-keywords|product-pages|automations)\s+(?:create|update|add|sync|run)/
 for (const path of [accountHealth, structureAudit]) {
@@ -82,11 +80,37 @@ for (const path of [accountHealth, structureAudit]) {
   if (WRITE_COMMAND.test(uses)) fail(path, `audit playbook declares a write command in uses: ${uses}`)
 }
 
+// The standard metric set. Both reporting workflows request all of it in the single overview call
+// they already make, so trimming a row saves nothing and only makes the report less decidable.
+const STANDARD_METRICS = [
+  'spend',
+  'impressions',
+  'taps',
+  'avg_cpt',
+  'total_installs',
+  'total_avg_cpi',
+  'cost_per_trial',
+  'cost_per_paid',
+]
+const NO_INSTALL_GAP = 'Never compare Apple install counts with Adapty install counts'
+const GAP_REMNANTS = [
+  'adapty_installs',
+  'absolute_gap',
+  'relative_gap',
+  'different attribution and event definitions',
+]
+
+for (const path of [accountHealth, weekly, reviewCommand]) {
+  for (const metric of STANDARD_METRICS) requireText(path, `\`${metric}\``, `standard metric ${metric}`)
+}
+for (const path of [accountHealth, weekly, auditSkill, reviewCommand]) {
+  for (const remnant of GAP_REMNANTS) forbidText(path, remnant, `install-gap remnant: ${remnant}`)
+}
+for (const path of [accountHealth, weekly, auditSkill]) {
+  requireText(path, NO_INSTALL_GAP, 'explicit install-gap non-goal')
+}
 for (const path of [accountHealth, weekly]) {
-  requireText(path, 'total_installs', 'Apple install metric')
-  requireText(path, 'adapty_installs', 'Adapty install metric')
-  requireText(path, 'only when', 'zero-safe percentage rule')
-  requireText(path, 'different attribution and event definitions', 'plain install-gap explanation')
+  requireText(path, 'whether the app offers a free trial', 'free-trial gate for cost_per_trial')
 }
 if (frontmatterValue(read(weekly), 'risk') !== 'read-only') fail(weekly, 'weekly check-in must stay read-only')