cx-listing-playbook 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +64 -2
  3. package/package.json +48 -4
  4. package/prompts/listing-create.md +5 -0
  5. package/prompts/listing-review.md +5 -0
  6. package/prompts/listing-watch.md +7 -0
  7. package/research/README.md +648 -0
  8. package/research/angles/account-health.md +482 -0
  9. package/research/angles/ai-shopping-surfaces.md +438 -0
  10. package/research/angles/brand-protection-and-catalog-contribution.md +489 -0
  11. package/research/angles/competitor-discovery.md +369 -0
  12. package/research/angles/competitor-set.md +589 -0
  13. package/research/angles/inventory-and-fulfillment.md +927 -0
  14. package/research/angles/listing-content-and-health.md +935 -0
  15. package/research/angles/marketplaces-and-languages.md +386 -0
  16. package/research/angles/off-listing-traffic.md +290 -0
  17. package/research/angles/offer-competition-and-hijackers.md +543 -0
  18. package/research/angles/own-traffic-funnel.md +607 -0
  19. package/research/angles/paid-keywords.md +689 -0
  20. package/research/angles/price-position.md +875 -0
  21. package/research/angles/returns.md +508 -0
  22. package/research/angles/reviews-and-qa.md +637 -0
  23. package/research/angles/search-query-performance.md +544 -0
  24. package/research/angles/search-rank-and-volume.md +463 -0
  25. package/research/angles/seasonality-and-events.md +647 -0
  26. package/research/angles/vendor-and-hybrid.md +831 -0
  27. package/research/elements/a-plus-content.md +642 -0
  28. package/research/elements/attributes-and-browse-nodes.md +901 -0
  29. package/research/elements/badges-and-placements.md +443 -0
  30. package/research/elements/brand-story-and-store.md +605 -0
  31. package/research/elements/bullet-points.md +664 -0
  32. package/research/elements/description.md +460 -0
  33. package/research/elements/images-and-video.md +720 -0
  34. package/research/elements/search-terms.md +688 -0
  35. package/research/elements/title.md +841 -0
  36. package/research/elements/variations.md +710 -0
  37. package/research/method/amazon-change-calendar.md +354 -0
  38. package/research/method/effect-measurement.md +878 -0
  39. package/research/method/funnel-and-search.md +662 -0
  40. package/research/method/help-page-access.md +432 -0
  41. package/research/method/listing-create.md +389 -0
  42. package/research/method/listing-policies.md +913 -0
  43. package/research/method/listing-writes.md +1099 -0
  44. package/research/method/report-lifecycle.md +586 -0
  45. package/research/method/seller-central-only-tools.md +545 -0
  46. package/research/method/sp-api-access.md +400 -0
  47. package/research/method/triggers.md +844 -0
  48. package/skills/effect-review/SKILL.md +34 -0
  49. package/skills/effect-review/references/confounders.md +114 -0
  50. package/skills/effect-review/references/design.md +73 -0
  51. package/skills/effect-review/references/verdicts.md +91 -0
  52. package/skills/listing-change-log/SKILL.md +24 -0
  53. package/skills/listing-change-log/references/record.md +97 -0
  54. package/skills/listing-create/SKILL.md +68 -0
  55. package/skills/listing-create/references/answers.md +18 -0
  56. package/skills/listing-create/references/family.md +10 -0
  57. package/skills/listing-create/references/request.md +44 -0
  58. package/skills/listing-review/SKILL.md +43 -0
  59. package/skills/listing-review/references/figures.md +94 -0
  60. package/skills/listing-review/references/funnel.md +96 -0
  61. package/skills/listing-review/references/good-listing.md +117 -0
  62. package/skills/listing-review/references/policy.md +98 -0
  63. package/skills/listing-review/references/reports.md +87 -0
  64. package/skills/listing-review/references/signals.md +80 -0
  65. package/skills/listing-review/references/watch.md +84 -0
  66. package/skills/listing-review/references/write-path.md +101 -0
  67. package/skills/listing-review/references/writing.md +39 -0
  68. package/skills/listing-review/scripts/report.sh +170 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ComChatX
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,65 @@
1
- # Temporary Holding Version
1
+ # cx-listing-playbook
2
2
 
3
- 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.
3
+ A [pi](https://pi.dev) package for the work on an Amazon listing: creating it, how it performs and why, a log of each change, and how to judge whether a change worked. It is written for the assistant in a [ComChatX](https://comchatx.com) seller's box, and reads the seller's Amazon account through the box's `cx` command.
4
+
5
+ It is text and one script. Its changes are in [CHANGELOG.md](CHANGELOG.md). Every sentence of the skills ends with the research item it rests on, and the research is in [`research/`](research/README.md).
6
+
7
+ ## What it holds
8
+
9
+ | | What the model reads |
10
+ |---|---|
11
+ | `skills/listing-review` | The funnel and which element serves each stage, what Amazon's own answers show about a listing, the signals that something changed, which file carries each figure, how a write is validated (`references/writing.md`), and `scripts/report.sh` |
12
+ | `skills/listing-change-log` | One file per listing change: before, after, what was expected and from which file, the words bet on, the seller's decision, the request as it would be sent, Amazon's receipt id and the observation window |
13
+ | `skills/listing-create` | Creating a listing in the stores the seller names: new item or existing ASIN, the product type and each store's schema, identity, the request built from the seller's data, the preview (sent as a read, since it persists nothing), the write on the seller's word, the read-back until buyable and discoverable, and variation families |
14
+ | `skills/effect-review` | Experiments, baseline and observation windows, controls, confounders, and the three verdicts: held, not held, cannot tell |
15
+ | `prompts/listing-create.md` | `/listing-create <marketplaces> <your words, and where the product's data is>`: hands the seller's words to cx, e.g. `/listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货` |
16
+ | `prompts/listing-review.md` | `/listing-review <ASIN>`: the listing and its issues, the market since last time, a proposal with its reasons |
17
+ | `prompts/listing-watch.md` | `/listing-watch <ASIN> <your words>`: writes the standing instruction for that listing from the seller's words, e.g. `/listing-watch <ASIN> 以后每天帮我盯着这个 listing,有要改的告诉我,没事别吵` |
18
+
19
+ Each skill's detail is under its `references/`.
20
+
21
+ ## Files in the seller's tree
22
+
23
+ | Place | Holds |
24
+ |---|---|
25
+ | `/tenant/listings/<ASIN>/watch.md` | The standing instruction `/listing-watch` writes |
26
+ | `/tenant/listings/<ASIN>/changes/` | One file per listing change; changes made together are one change |
27
+ | `/tenant/reports/<reportType>/<ask>/<n>/` | One report of that ask: `receipt.json` with the report id, Amazon's status and `createdTime`, each reply as Amazon gave it, and the document |
28
+
29
+ ## The report script
30
+
31
+ ```bash
32
+ scripts/report.sh <reportType> --origin <origin> --marketplace <id>[,<id>...] [--start <ISO 8601>] [--end <ISO 8601>] \
33
+ [--option <name>=<value>]... --wait <seconds> [--every <seconds>]
34
+ ```
35
+
36
+ It asks Amazon's Reports API through `cx raw amazon-sp-api`: `createReport`, `getReport` until a terminal status or the `--wait` ceiling, `getReportDocument` and the document, decompressed, landed beside the receipt. Each run asks for a report of its own, except that it carries on the ask's report not yet landed: one still queued at the ceiling ends the run with its id and status (exit 3) for the next run to carry on. Earlier reports stay as they landed. It has no rate limiter and no retry of its own. Report types, their options and their periods are the `amazon-sp-api` skill's (`references/door.md`). It needs `bash`, `jq`, `curl` and `gzip`, which the box has.
37
+
38
+ ## What it needs
39
+
40
+ pi, and in the box the `cx` command with the Amazon SP-API source; Keepa where a skill names a Keepa field. It reaches no network itself except the one document link Amazon hands the script.
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ pi install npm:cx-listing-playbook # for you, in ~/.pi/agent/settings.json
46
+ pi install -l npm:cx-listing-playbook # for one project, in .pi/settings.json
47
+ pi remove npm:cx-listing-playbook
48
+ ```
49
+
50
+ On ComChatX, a seller installs it from the Plugins page.
51
+
52
+ ## Develop
53
+
54
+ ```bash
55
+ npm ci
56
+ npm run typecheck
57
+ npm test # pi at the pin loads the package and expands every template; every text line cites a research item;
58
+ # the script runs against a stub cx
59
+ ```
60
+
61
+ `TENANT_TREE` moves the script's tree from `/tenant` for a run outside the box, as the tests do.
62
+
63
+ ## Licence
64
+
65
+ MIT. See [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "cx-listing-playbook",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "A pi package for the work on an Amazon listing: how it performs and why, a log of each change, and how to judge one.",
5
+ "license": "MIT",
6
+ "author": "ComChatX",
7
+ "homepage": "https://github.com/comchatx/cx-listing-playbook#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/comchatx/cx-listing-playbook.git"
11
+ },
12
+ "bugs": "https://github.com/comchatx/cx-listing-playbook/issues",
13
+ "keywords": [
14
+ "pi-package"
15
+ ],
16
+ "type": "module",
17
+ "pi": {
18
+ "skills": [
19
+ "./skills"
20
+ ],
21
+ "prompts": [
22
+ "./prompts"
23
+ ]
24
+ },
25
+ "files": [
26
+ "skills",
27
+ "prompts",
28
+ "research"
29
+ ],
30
+ "scripts": {
31
+ "typecheck": "tsc --noEmit",
32
+ "test": "vitest run"
33
+ },
34
+ "devDependencies": {
35
+ "@earendil-works/pi-ai": "1.1.0",
36
+ "@earendil-works/pi-coding-agent": "1.1.0",
37
+ "@types/node": "26.2.0",
38
+ "typescript": "7.0.2",
39
+ "vitest": "4.1.11"
40
+ },
41
+ "overrides": {
42
+ "@earendil-works/chord": "1.1.0",
43
+ "@earendil-works/pi-ai": "1.1.0",
44
+ "@earendil-works/pi-mcp": "1.1.0",
45
+ "@earendil-works/pi-tui": "1.1.0",
46
+ "@earendil-works/pi-codemode": "1.1.0",
47
+ "@earendil-works/pi-agent-core": "1.1.0",
48
+ "@earendil-works/pi-telemetry": "1.1.0"
49
+ }
50
+ }
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Create Amazon listings from your own words and your product's data — e.g. /listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货
3
+ argument-hint: "<marketplaces> <your words, and where the product's data is>"
4
+ ---
5
+ Create my listing in $1 from my words: ${@:2}
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Review one Amazon listing — how it is doing, what changed, and what to change
3
+ argument-hint: "<ASIN>"
4
+ ---
5
+ Review my listing $1: the listing and its issues, the market since you last looked, and your proposal with its reasons.
@@ -0,0 +1,7 @@
1
+ ---
2
+ description: Write the standing instruction for watching one listing, from your own words — e.g. /listing-watch <ASIN> 以后每天帮我盯着这个 listing,有要改的告诉我,没事别吵
3
+ argument-hint: "<ASIN> <what you want, in your words>"
4
+ ---
5
+ Write the standing instruction for my listing $1 from my words: ${@:2}
6
+
7
+ It says what to watch, how often, when to tell me and when to stay quiet, where to tell me, and whether you may change anything without asking me.