@comchatx/cx-sponsored-ads-playbook 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ComChatX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+cx finds why spend or sales moved in your Sponsored Products, Brands and Display ads and proposes changes backed by figures. Later, from Amazon's change history, it tells if a change worked, did not, or cannot be told yet.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Some things you can ask:
+
+- Why did my ad spend rise last week while sales stayed flat?
+- Why did B0EXAMPLE1's ads suddenly stop getting impressions?
+- Which campaigns keep running out of budget, and how much should I add?
+
+To have cx review your ads every week, also install cx-schedule.
+
+## What it uses
+
+- **Amazon Ads:** your Amazon advertising accounts, connected on the Amazon Ads plugin. cx reads your campaigns and reports there, and changes your bids, budgets and targets there.
+- **Amazon SP-API,** where you have it: your Buy Box, stock, fees and total sales, so cx can set your ads against your whole store.
+- **Keepa,** where you have it: Buy Box and rank history.

package/README.zh-CN.md

@@ -0,0 +1,15 @@
+cx 检查你的商品推广、品牌推广和展示型推广，找出花费或销量变化的原因，提出修改，并附上理由和依据的数据。之后问起某次改动，cx 会对照亚马逊的改动记录和报告，判断已见效、未见效，还是暂时无法确定。
+
+你可以这样问：
+
+- 上周广告花费涨了，销量却没动，为什么？
+- B0EXAMPLE1 的广告怎么突然没曝光了？
+- 哪些广告活动经常预算不够，该加到多少？
+
+如果想让 cx 每周定时复盘广告，再装上 cx-schedule。
+
+## 用到的数据
+
+- **Amazon Ads**：你的亚马逊广告账户，在 Amazon Ads 插件里连接。cx 在这里读取广告活动和报告，也在这里修改出价、预算和投放。
+- **Amazon SP-API**（如果你装了）：你的 Buy Box、库存、费用和总销量，让 cx 把广告放到整个店铺里看。
+- **Keepa**（如果你装了）：Buy Box 和排名的历史。

package/package.json

@@ -1,6 +1,130 @@
 {
   "name": "@comchatx/cx-sponsored-ads-playbook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Traces why ad spend or sales moved, then judges each fix.",
+  "license": "MIT",
+  "author": "ComChatX",
+  "comchatx": {
+    "about": "查出广告花费和销量变化的原因，改后判断是否见效。",
+    "mark": {
+      "line": "chart"
+    },
+    "section": "extensions",
+    "order": 51,
+    "skills": {
+      "ads-review": {
+        "zh": "分析广告表现，以及花费和销量变化的原因。",
+        "en": "How your ads perform, and why spend or sales moved."
+      },
+      "ads-launch": {
+        "zh": "判断新品能否投广告，并搭建首批广告活动。",
+        "en": "Whether a new product can advertise, and its first campaigns."
+      },
+      "ads-structure-and-targets": {
+        "zh": "分析广告活动的结构和每种投放会匹配什么。",
+        "en": "How campaigns are built, and what each target matches."
+      },
+      "ads-search-terms": {
+        "zh": "找出值得单独投放和该否定的搜索词。",
+        "en": "Search terms worth targeting, and ones to negate."
+      },
+      "ads-bids-and-budgets": {
+        "zh": "分析出价、版位和预算如何决定花费。",
+        "en": "How bids, placements and budgets decide what you spend."
+      },
+      "ads-seasons": {
+        "zh": "安排大促前后的预算、出价和促销。",
+        "en": "Budgets, bids and deals around Amazon's sales events."
+      },
+      "ads-economics": {
+        "zh": "算出广告订单的利润和广告对总销量的贡献。",
+        "en": "What an ad sale earns, and what ads add to total sales."
+      },
+      "ads-change": {
+        "zh": "查广告改动记录，判断一次改动是否见效。",
+        "en": "Amazon's change history, and whether a change worked."
+      }
+    },
+    "prompts": {
+      "ads-review": {
+        "zh": "复盘最近几周的广告，并提出修改。"
+      },
+      "ads-launch": {
+        "zh": "为新品开始投广告，从能否投放到首批广告活动。"
+      },
+      "ads-harvest": {
+        "zh": "梳理搜索词，找出值得单独投放和该否定的词。"
+      },
+      "ads-season": {
+        "zh": "为下一个亚马逊大促准备好广告。"
+      },
+      "ads-margin": {
+        "zh": "算出广告订单能赚多少，以及盈亏平衡的 ACOS。"
+      },
+      "ads-brand": {
+        "zh": "看看谁在你的品牌搜索词和商品页上投广告，守住要花多少钱。"
+      },
+      "ads-change-review": {
+        "zh": "判断某一天的广告改动是否见效。"
+      }
+    },
+    "builds": [
+      {
+        "on": "@comchatx/cx-amazon-ads",
+        "need": "required"
+      },
+      {
+        "on": "cx-amazon-sp-api",
+        "need": "optional"
+      },
+      {
+        "on": "cx-keepa",
+        "need": "optional"
+      }
+    ]
+  },
+  "homepage": "https://github.com/comchatx/cx-sponsored-ads-playbook#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comchatx/cx-sponsored-ads-playbook.git"
+  },
+  "bugs": "https://github.com/comchatx/cx-sponsored-ads-playbook/issues",
+  "keywords": [
+    "pi-package"
+  ],
+  "type": "module",
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "files": [
+    "skills",
+    "prompts",
+    "research",
+    "README.zh-CN.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "26.2.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "overrides": {
+    "@earendil-works/chord": "1.1.0",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-mcp": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@earendil-works/pi-codemode": "1.1.0",
+    "@earendil-works/pi-agent-core": "1.1.0",
+    "@earendil-works/pi-telemetry": "1.1.0"
+  }
+}

package/prompts/ads-brand.md

@@ -0,0 +1,5 @@
+---
+description: "See who advertises on your brand's searches and pages, and what holding them costs."
+argument-hint: "[brand and your words]"
+---
+Show me who advertises on my brand's searches and product pages, and what holding those places costs me. $@

package/prompts/ads-change-review.md

@@ -0,0 +1,5 @@
+---
+description: "Tell whether the ad changes made on a given day worked."
+argument-hint: "<date> [your words]"
+---
+Tell me whether the ad changes made on $1 held, did not, or cannot be told yet, and how sure you are. ${@:2}

package/prompts/ads-harvest.md

@@ -0,0 +1,5 @@
+---
+description: "Go through your search terms for ones to target and ones to negate."
+argument-hint: "[your words]"
+---
+Go through my search terms since the last pass: which to move into targets of their own, which to negate, and why. $@

package/prompts/ads-launch.md

@@ -0,0 +1,5 @@
+---
+description: "Start a new product's ads, from whether it can serve to its first campaigns."
+argument-hint: "<ASIN> [marketplaces and your words]"
+---
+Get my product $1 advertising: whether it can serve, and the first campaigns you would set up for it, with your reasons. ${@:2}

package/prompts/ads-margin.md

@@ -0,0 +1,5 @@
+---
+description: "Work out what an ad sale earns you, and your break-even ACOS."
+argument-hint: "[SKUs or ASINs and your words]"
+---
+Work out what an ad sale is worth on my products, from fees and costs to break-even ACOS, and what that makes my targets. $@

package/prompts/ads-review.md

@@ -0,0 +1,5 @@
+---
+description: "Review your ads over the last few weeks, and propose changes."
+argument-hint: "[your words]"
+---
+Review my Amazon sponsored ads over the last few weeks: how spend and sales went, what moved and why, and what you would change, with your reasons. $@

package/prompts/ads-season.md

@@ -0,0 +1,5 @@
+---
+description: "Prepare your ads for Amazon's next sales event."
+argument-hint: "[event and your words]"
+---
+Get my sponsored ads ready for the next Amazon event in my marketplaces: its dates, budgets, bids and deals, with your reasons. $@