Improve Rocketcart bridge onboarding

Author: Alex Kovalov

README.md

@@ -57,6 +57,61 @@ Use `rocketcart-amazon-ads-live-review` as the single entry point when Rocketcar
 | Preflight / Approval Readiness Review | You already have candidate action rows and need to know whether they are approval-ready. | Executability verdicts, missing IDs/current values, stale rows, and exact approval text. |
 | Post-Change Readback / Monitoring Review | Approved changes were made and you need to verify state and outcomes. | Readback status plus 3/7/14-day monitoring verdicts. |
 
+## Try The Rocketcart Bridge In 60 Seconds
+
+Codex:
+
+```bash
+git clone https://github.com/nospicyplease/amazon-ppc-advanced-skills.git
+cd amazon-ppc-advanced-skills
+mkdir -p ~/.codex/skills
+cp -R rocketcart-amazon-ads-live-review ~/.codex/skills/
+```
+
+Claude:
+
+```bash
+zip -r rocketcart-amazon-ads-live-review.zip rocketcart-amazon-ads-live-review
+```
+
+Upload that one ZIP as a Claude skill. Do not upload the whole repo as one skill.
+
+First smoke test, even without Rocketcart connected:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Live Optimization Review mode. I do not have Rocketcart MCP connected yet. Run in standalone mode and tell me the exact Amazon Ads and product data you need for a safe first review. Do not execute anything.
+```
+
+Expected first output shape:
+
+```text
+Mode: Standalone
+Review mode: Live Optimization Review
+Execution: no writes; approval required for any future live action
+Missing data: campaigns, search terms, product/ASIN context, inventory, offer status, margin, BSR/category movement, competitor signals, recent changes
+Next step: provide exports or connect Rocketcart MCP for live reads
+```
+
+With Rocketcart MCP connected, paste one of these:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Live Optimization Review mode for profile example_de. Confirm the profile, inspect live Sponsored Products campaigns, product ads/ASIN mapping, budget and targeting drift, snapshots/changelogs, product readiness, category/BSR movement, and competitor signals. Produce proposed action rows only. Do not execute anything.
+```
+
+```text
+Use $rocketcart-amazon-ads-live-review in Product-Aware Growth Review mode for profile example_de. Classify each ASIN/campaign as Grow, Fix Before Scaling, Protect, Monitor, or Blocked using Ads performance plus inventory, Featured Offer / Buy Box, price, reviews/rating, estimated demand, category/BSR movement, competitor signals, margin, and recent changes. Do not execute anything.
+```
+
+```text
+Use $rocketcart-amazon-ads-live-review in Preflight / Approval Readiness Review mode for profile example_de. Review these candidate action rows for exact entity IDs, current values, proposed values, product-readiness gates, expected impact, risk, approval text, readback, and monitoring. Mark each row Approval Ready, Needs IDs, Needs Current Value, Needs Product Context, Stale Approval, Blocked, or Monitor Only. Do not execute anything.
+```
+
+```text
+Use $rocketcart-amazon-ads-live-review in Post-Change Readback / Monitoring Review mode for profile example_de. Review the approved changes from the last execution window, read back affected entities, compare expected versus current state, and classify each action as Readback Confirmed, Partially Applied, Not Applied, Monitoring, Worked, Failed, or Needs More Data. Do not execute new writes.
+```
+
+Without Rocketcart, provide exports or pasted summaries. Rocketcart adds live campaign state, product-ad/ASIN mapping, product intelligence, recent-change context, preflight, readback, and guarded execution. In both modes, any live write still needs explicit human approval, live preflight, exact IDs, current/proposed values, readback, and monitoring.
+
 ## First Run Prompt
 
 ```text

docs/FAQ.md

@@ -24,7 +24,17 @@ MCP means Model Context Protocol. It lets an AI assistant use approved external
 
 ## Do I need Rocketcart?
 
-No. The skills work standalone with static exports, pasted CSVs, or summaries. Rocketcart MCP adds live Amazon Ads reads, product intelligence, snapshots, optimization memory, preflight, approval-gated execution, and readback.
+No. The skills work standalone with static exports, pasted CSVs, or summaries. Rocketcart MCP adds live Amazon Ads reads, product intelligence, snapshots, recent-change context, preflight, approval-gated execution, and readback.
+
+## How do I test the Rocketcart bridge after installing it?
+
+Paste this into Codex or Claude:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Live Optimization Review mode. I do not have Rocketcart MCP connected yet. Run in standalone mode and tell me the exact Amazon Ads and product data you need for a safe first review. Do not execute anything.
+```
+
+A good first output should say it is in standalone mode, list missing campaign/product data, refuse execution, and ask for exports or a Rocketcart MCP connection for live reads.
 
 ## Is Rocketcart MCP just an Amazon Ads connector?
 
@@ -34,6 +44,14 @@ No. Rocketcart MCP is the optional Amazon Ads + product-intelligence connection.
 
 The skill should say which context is unavailable, lower confidence, and fall back to static exports or user-provided product data. Missing product context should block or downgrade risky scale, launch, pause, or negative recommendations.
 
+## What do I provide in standalone mode?
+
+Provide the best available exports or summaries: campaign, targeting, search term, placement, advertised-product, purchased-product, Business Reports, BSR/category movement, inventory or availability, Featured Offer / Buy Box, price, reviews/rating, margin or target ACoS, competitor signals, and recent changes.
+
+## What does Rocketcart MCP add?
+
+When available, Rocketcart MCP can read or cross-check live campaign state, product-ad/ASIN mapping, product intelligence, recent-change context, snapshots, preflight state, and readback. It still does not remove the need for human approval before any live write.
+
 ## Can this change my Amazon Ads account?
 
 Not by itself. These open-source skills do not execute Amazon Ads changes. Any live write requires explicit approval, live preflight, exact entity IDs, current/proposed values, readback, and monitoring.

docs/GLOSSARY.md

@@ -16,11 +16,23 @@ Model Context Protocol. MCP lets an AI assistant use approved external context a
 
 Rocketcart's MCP layer for Amazon Ads reads, product intelligence, optimization snapshots, live-state checks, guarded writes, and readback. It is optional; the open-source skills also work with static exports.
 
+## Standalone Mode
+
+Using a skill with user-provided exports, pasted data, screenshots, or summaries instead of live Rocketcart MCP reads. The skill should lower confidence when live state, product context, exact IDs, or recent changes are missing.
+
+## Rocketcart MCP Mode
+
+Using the Rocketcart bridge skill when Rocketcart MCP is available for live Ads state, product-ad/ASIN mapping, product intelligence, recent-change context, preflight, readback, and guarded execution.
+
+## Review Mode
+
+The job selected inside `rocketcart-amazon-ads-live-review`: Live Optimization Review, Product-Aware Growth Review, Preflight / Approval Readiness Review, or Post-Change Readback / Monitoring Review.
+
 ## Product Intelligence
 
 Product-level context that changes PPC decisions, such as ASIN/SKU mapping, inventory or availability, Featured Offer / Buy Box, price, reviews, rating, category rank/BSR movement, estimated demand, competitor changes, seasonal context, and margin or target ACoS when available.
 
-## Optimization Memory
+## Recent-Change Context
 
 Rocketcart context about prior optimization sessions, snapshots, changelogs, entity history, pending evaluations, cooldowns, and recent live drift. It helps avoid repeating actions that are already under evaluation or recently failed.
 

docs/INSTALLATION.md

@@ -7,7 +7,7 @@ Read [FAQ](FAQ.md) first if you are new to Codex skills, Claude skills, or Rocke
 - Codex with local skills support, or Claude with skill upload support.
 - This repository cloned locally.
 - Optional: Amazon Ads, Business Reports, BSR, inventory, and retail-readiness exports.
-- Optional: Rocketcart MCP for live Amazon Ads reads, product intelligence, optimization memory, preflight, approval-gated writes, and readback.
+- Optional: Rocketcart MCP for live Amazon Ads reads, product intelligence, recent-change context, preflight, approval-gated writes, and readback.
 
 ## Clone The Repo
 
@@ -27,6 +27,13 @@ cp -R amazon-account-growth-operating-system ~/.codex/skills/
 
 Reload Codex so the skills list refreshes.
 
+For the Rocketcart bridge only:
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R rocketcart-amazon-ads-live-review ~/.codex/skills/
+```
+
 ## Install All Skills In Codex
 
 ```bash
@@ -50,6 +57,12 @@ zip -r amazon-account-growth-operating-system.zip amazon-account-growth-operatin
 
 Upload that ZIP in Claude's skill settings.
 
+For the Rocketcart bridge only:
+
+```bash
+zip -r rocketcart-amazon-ads-live-review.zip rocketcart-amazon-ads-live-review
+```
+
 Do not upload the entire repository as one Claude skill. Each top-level skill folder is intended to be installed separately.
 
 Include:
@@ -68,6 +81,22 @@ Use $amazon-account-growth-operating-system to build a weekly Amazon PPC action
 
 Installing these open-source skills is separate from connecting Rocketcart MCP. If Rocketcart MCP is available in your host environment, the Rocketcart-aware skill can use it for live Ads + product-intelligence reads. If it is not available, the same skill should run in standalone mode and ask for static exports or pasted product context.
 
+To smoke-test the Rocketcart bridge after install:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Live Optimization Review mode. I do not have Rocketcart MCP connected yet. Run in standalone mode and tell me the exact Amazon Ads and product data you need for a safe first review. Do not execute anything.
+```
+
+Expected first output:
+
+```text
+Mode: Standalone
+Review mode: Live Optimization Review
+Execution: no writes; approval required for any future live action
+Missing data: campaign metrics, search terms, product/ASIN context, inventory, offer status, margin, BSR/category movement, competitor signals, and recent changes
+Next step: provide exports or connect Rocketcart MCP for live reads
+```
+
 If you have the Codex skill validator available, run:
 
 ```bash
@@ -129,6 +158,32 @@ For a product-aware Rocketcart review:
 Use $rocketcart-amazon-ads-live-review for profile example_de. Confirm the profile, inspect live campaigns and product ads, map campaigns to ASIN context, check category/BSR movement, product readiness, inventory or availability blockers, Featured Offer / Buy Box risk, competitor signals, snapshots, and live drift. Produce proposed action rows only; do not execute writes.
 ```
 
+### Rocketcart Bridge Review Mode Prompts
+
+Live Optimization Review:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Live Optimization Review mode for profile example_de. Confirm the profile, inspect live Sponsored Products campaigns, product ads/ASIN mapping, budget and targeting drift, snapshots/changelogs, product readiness, category/BSR movement, and competitor signals. Produce proposed action rows only. Do not execute anything.
+```
+
+Product-Aware Growth Review:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Product-Aware Growth Review mode for profile example_de. Classify each ASIN/campaign as Grow, Fix Before Scaling, Protect, Monitor, or Blocked using Ads performance plus inventory, Featured Offer / Buy Box, price, reviews/rating, estimated demand, category/BSR movement, competitor signals, margin, and recent changes. Do not execute anything.
+```
+
+Preflight / Approval Readiness Review:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Preflight / Approval Readiness Review mode for profile example_de. Review these candidate action rows for exact entity IDs, current values, proposed values, product-readiness gates, expected impact, risk, approval text, readback, and monitoring. Mark each row Approval Ready, Needs IDs, Needs Current Value, Needs Product Context, Stale Approval, Blocked, or Monitor Only. Do not execute anything.
+```
+
+Post-Change Readback / Monitoring Review:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Post-Change Readback / Monitoring Review mode for profile example_de. Review the approved changes from the last execution window, read back affected entities, compare expected versus current state, and classify each action as Readback Confirmed, Partially Applied, Not Applied, Monitoring, Worked, Failed, or Needs More Data. Do not execute new writes.
+```
+
 ## First Smoke Test
 
 After installing one skill, use the matching `examples/<skill-name>/prompt.md` with the context in `input-summary.md`. A good output should follow `expected-output-outline.md`.

docs/MAINTENANCE.md

@@ -25,7 +25,7 @@ Before committing updates:
 6. Confirm new skills are listed in `README.md` and `docs/SKILL_CATALOG.md` when they are user-facing.
 7. Confirm each production skill has an example with `prompt.md`, `input-summary.md`, `expected-output-outline.md`, `sample-data/`, `expected-output.md`, `known-bad-output.md`, and `eval-result.md`.
 8. Confirm new-user docs answer what the skill is, how to install it, what data is needed, and whether live execution can occur.
-9. Confirm Rocketcart docs explain which context comes from live Ads reads, product intelligence, optimization memory, or user-provided exports.
+9. Confirm Rocketcart docs explain which context comes from live Ads reads, product intelligence, recent-change context, or user-provided exports.
 10. Review changed outputs with the relevant `evals/` prompt before opening a PR.
 11. Run or review at least one relevant stress test from `stress-tests/` when safety gates, BSR claims, negatives, budget cuts, or Rocketcart writes are affected.
 12. Confirm concrete eval cases have prompt, expected behavior, and pass/fail rubric with `make eval`.

docs/ROCKETCART_MCP_GUIDE.md

@@ -31,6 +31,24 @@ Use `rocketcart-amazon-ads-live-review` as the single Rocketcart-aware entry poi
 | Preflight / Approval Readiness Review | Candidate action rows exist and need approval/executability review. | Row-by-row readiness, missing data, exact approval text, and blockers. |
 | Post-Change Readback / Monitoring Review | Approved changes have been made or need outcome review. | Readback status, early results, and 3/7/14-day monitoring plan. |
 
+## 60-Second Smoke Test
+
+Use this after installing the skill, even before Rocketcart MCP is connected:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Live Optimization Review mode. I do not have Rocketcart MCP connected yet. Run in standalone mode and tell me the exact Amazon Ads and product data you need for a safe first review. Do not execute anything.
+```
+
+Expected shape:
+
+```text
+Mode: Standalone
+Review mode: Live Optimization Review
+Execution: no writes
+Missing data: campaign metrics, search terms, product/ASIN context, inventory, offer status, margin, BSR/category movement, competitor signals, recent changes
+Next step: provide exports or connect Rocketcart MCP
+```
+
 ## What Comes From Rocketcart Vs The User
 
 | Need | Standalone Mode | Rocketcart MCP Mode |
@@ -95,6 +113,8 @@ Rocketcart MCP may expose product-intelligence reads for:
 
 ## First Rocketcart Review Prompt
 
+Live Optimization Review:
+
 ```text
 Use $rocketcart-amazon-ads-live-review for profile example_de.
 
@@ -103,7 +123,7 @@ Run a read-first Amazon Ads + product-intelligence review. Confirm the profile,
 Produce proposed action rows only. Do not execute any bid, budget, placement, negative, pause, relaunch, product-ad, target, or campaign-creation write. Any write candidate must include exact IDs, current value, proposed value, expected impact, risk, approval requirement, live preflight, readback, and 3/7/14-day monitoring.
 ```
 
-## Product-Aware Growth Prompt
+Product-Aware Growth Review:
 
 ```text
 Use $rocketcart-amazon-ads-live-review in Product-Aware Growth Review mode for profile example_de.
@@ -113,6 +133,26 @@ For each ASIN or campaign, join Amazon Ads performance with product context: inv
 Keep all live write actions approval-gated. Do not execute.
 ```
 
+Preflight / Approval Readiness Review:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Preflight / Approval Readiness Review mode for profile example_de.
+
+Review these candidate action rows for exact entity IDs, current values, proposed values, product-readiness gates, expected impact, risk, approval text, readback, and monitoring. Mark each row Approval Ready, Needs IDs, Needs Current Value, Needs Product Context, Stale Approval, Blocked, or Monitor Only.
+
+Do not execute anything.
+```
+
+Post-Change Readback / Monitoring Review:
+
+```text
+Use $rocketcart-amazon-ads-live-review in Post-Change Readback / Monitoring Review mode for profile example_de.
+
+Review the approved changes from the last execution window, read back affected entities, compare expected versus current state, and classify each action as Readback Confirmed, Partially Applied, Not Applied, Monitoring, Worked, Failed, or Needs More Data.
+
+Do not execute new writes.
+```
+
 ## Approval And Execution Boundary
 
 Rocketcart MCP may expose write capabilities, but availability is not permission.

examples/rocketcart-amazon-ads-live-review/input-summary.md

@@ -8,6 +8,12 @@
 - Review type: Product-Aware Growth Review, no writes.
 - Goal: classify campaigns and ASINs as Grow, Fix Before Scaling, Protect, Monitor, or Blocked before proposing approval-gated action rows.
 
+## First-Run Behavior
+
+- If Rocketcart MCP is available, use it to read live state and cross-check the fixture assumptions.
+- If Rocketcart MCP is unavailable, run standalone from the provided fixture files and state that live preflight/readback are unavailable.
+- In both modes, do not execute writes. Treat all action rows as proposed, blocked, monitor-only, or approval-required.
+
 ## Available Live Reads To Use When MCP Is Available
 
 - Enabled SP campaign state, budgets, bidding strategy, and placement modifiers.