@salesforce/b2c-dx-mcp 2.1.1 → 3.0.0

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-cap/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: b2c-cap
+description: Manage Commerce App Packages (CAPs), also called commerce apps or apps, and commerce features using the b2c CLI. Use this skill whenever the user needs to validate, package, install, uninstall, list, or pull commerce apps on B2C Commerce instances, view configuration tasks, or pull app sources for cartridge deployment or Storefront Next development. Also use when checking which apps are installed on an instance, inspecting app details or versions, or managing app lifecycle — even if they just say "what apps do I have", "list my commerce apps", "which CAPs are installed", "install this app", "pull app sources", or "show installed apps".
+---
+
+# B2C CAP Skill
+
+Use the `b2c` CLI plugin to **validate, package, install, uninstall, list, and pull** Commerce App Packages (CAPs) and commerce features on Salesforce B2C Commerce instances.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli cap list`).
+
+## Configuration & Authentication
+
+The CLI auto-discovers the target instance and credentials from `SFCC_*` environment variables (including project `.env`), the selected project-local or shared `dw.json`, and configuration plugins. `package.json` supplies only non-sensitive defaults. **Flags like `--server`, `--client-id`, and `--client-secret` are usually unnecessary** — only pass them to override what's auto-detected.
+
+Run `b2c setup inspect` to see the resolved configuration and which source provided each value (use `--json` for scripting; secrets stay masked by default). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+The remote commands (`cap install`, `cap uninstall`, `cap tasks`, `cap pull`, and `cap list` without `--local`) require OAuth for SCAPI-first system-job execution and **WebDAV** access for uploading/downloading archives. In `auto` mode, job execution temporarily falls back to OCAPI when SCAPI definitively rejects the start request. WebDAV authenticates via `SFCC_USERNAME`/`SFCC_PASSWORD` (BM username + WebDAV access key), `--user-auth` for interactive browser login, or an Account Manager OAuth client granted WebDAV permissions on the `/impex` path; SCAPI is not a substitute for the WebDAV upload. The local-only commands (`cap validate`, `cap package`, and `cap list --local`) need no credentials.
+
+> **Authoring vs. operating:** This skill covers **operating** on existing CAPs against an instance (validate, package, install, uninstall, list, tasks, pull). To **author** a new CAP — scaffold the structure, generate IMPEX, run registry-grade validation, or submit to the registry — install the `cap-dev` skills with `b2c setup skills cap-dev`, or via the commerce-apps marketplace: `claude plugin marketplace add SalesforceCommerceCloud/commerce-apps` then `claude plugin install cap-dev`.
+
+## Examples
+
+### List Installed Features
+
+```bash
+# list all commerce features across all sites
+b2c cap list
+
+# list features for specific sites
+b2c cap list --site-id RefArch,SiteGenesis
+
+# list with full JSON output (includes config tasks and installation metadata)
+b2c cap list --json
+
+# list locally detected CAP directories
+b2c cap list --local
+```
+
+### Pull App Sources
+
+Pull installed Commerce App source packages for cartridge deployment or Storefront Next (`sfnext`) development. Pulled apps are extracted into `./commerce-apps/{name}/`. Depending on the app's architecture, a package may contain `cartridges/` and `impex/` data (backend or fullstack apps) and/or `storefront-next/` extensions (UI-only or fullstack apps) ready for use with the `sfnext` CLI.
+
+```bash
+# pull all registry apps to ./commerce-apps
+b2c cap pull
+
+# pull a specific app by name
+b2c cap pull avalara-tax
+
+# pull to a custom output directory
+b2c cap pull --output ./my-apps
+
+# pull apps installed on a specific site
+b2c cap pull --site-id RefArch
+```
+
+### View Configuration Tasks
+
+```bash
+# show configuration tasks with clickable BM links
+b2c cap tasks avalara-tax --site-id RefArch
+
+# get tasks as JSON
+b2c cap tasks avalara-tax --site-id RefArch --json
+```
+
+### Validate a CAP
+
+```bash
+# validate a local CAP directory
+b2c cap validate ./commerce-avalara-tax-app-v0.2.5
+
+# validate a CAP zip file (cap package produces {id}-v{version}.zip)
+b2c cap validate ./avalara-tax-v0.2.5.zip
+
+# validate with JSON output
+b2c cap validate ./commerce-avalara-tax-app-v0.2.5 --json
+```
+
+### Package a CAP
+
+```bash
+# package a CAP directory into a distributable zip
+b2c cap package ./commerce-avalara-tax-app-v0.2.5
+
+# package with a custom output path
+b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip
+```
+
+> Every cartridge under `cartridges/site_cartridges/` and `cartridges/bm_cartridges/` must have a `.project` file. `cap package` auto-creates an empty one for any cartridge missing it (existing `.project` files, empty or full Eclipse XML, are left untouched); `cap validate` fails if any cartridge is still missing one.
+
+### Install a CAP
+
+```bash
+# install a CAP directory on an instance
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch
+
+# install a pre-packaged zip
+b2c cap install ./avalara-tax-v0.2.5.zip --site-id RefArch
+
+# install with a timeout
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --timeout 600
+
+# skip validation before install
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate
+
+# remove the uploaded archive after install
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive
+
+# create a Storefront Next pull request for the app's storefront content
+# (requires a repository connected to the storefront; off by default)
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --create-pr
+```
+
+### Uninstall a CAP
+
+```bash
+# uninstall a commerce app (domain is looked up automatically)
+b2c cap uninstall avalara-tax --site-id RefArch
+```
+
+### More Commands
+
+See `b2c cap --help` for a full list of available commands and options in the `cap` topic.
+
+## Related Skills
+
+- `b2c-cli:b2c-job` - For running general jobs and site archive import/export
+- `b2c-cli:b2c-site-import-export` - For site archive structure and metadata XML patterns
+- `b2c-cli:b2c-code` - For deploying cartridges pulled from Commerce Apps

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-cip/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: b2c-cip
+description: Query CIP/CCAC sales, merchandising, payment, traffic, and API/controller analytics with the B2C CLI or MCP. Discover reports/tables, scope SQL, export results, and resolve analytics access.
+---
+
+# CIP analytics
+
+Use warehouse analytics for trends; use SCAPI/logs for current records and
+immediate diagnosis. If `b2c` is unavailable, use `npx @salesforce/b2c-cli`.
+
+## Choose the surface
+
+- Prefer MCP `cip_discover` / `cip_query` when available. Read
+  `skill://mcp/cip/SKILL.md` before querying and pass `skillRead: true`.
+  Discovery/config inspection is ungated. No terminal or token export needed.
+- Use CLI for explicit CLI requests, automation, or larger local CSV/JSON exports.
+  MCP limits results to 500 rows / 24 KB; `truncated` means incomplete output,
+  and `rowCount` counts returned rows. CLI defaults differ: date flags use the
+  current month unless overridden. Set explicit dates for the user's task.
+- Both surfaces use the same reports and toolkit configuration. Do not run both
+  to repeat a successful result.
+
+## Configuration and access
+
+Reuse resolved `tenantId`, `clientId`, `clientSecret` from `dw.json`, environment,
+instance selection, and configuration plugins. Use masked `b2c setup inspect`
+only if target/access is unclear; ask for missing values instead of guessing.
+Do not read secret files or export tokens for normal analytics requests.
+
+Requires Account Manager client credentials and the **Salesforce Commerce API**
+role with the target tenant in its tenant filter. User/SLAS/JWT flows do not apply.
+Overrides:
+
+| Value | CLI / environment |
+| --- | --- |
+| Tenant | `--tenant-id` (`--tenant`) / `SFCC_TENANT_ID` |
+| Client | `--client-id` / `SFCC_CLIENT_ID` |
+| Secret | `--client-secret` / `SFCC_CLIENT_SECRET` |
+| Analytics host | `--cip-host` / `SFCC_CIP_HOST` |
+| Force staging analytics | `--staging` / `SFCC_CIP_STAGING` |
+
+Tenants ending `_prd` select production analytics; other tenants select staging.
+Explicit host configuration wins. Staging analytics is a destination, not an
+instruction to change the target instance. Non-production data requires 26.1+
+**Enable Reports & Dashboards Data Tracking**. Production tenants in test realms
+can also need staging analytics. Dashboard: `https://ccac.stg.analytics.commercecloud.salesforce.com`.
+
+Missing configuration/availability:
+[analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac).
+Resolution details: `b2c-cli/b2c-config`. Read only the relevant section.
+
+## Discover and execute
+
+1. List/search reports; inspect the selected report's parameters. MCP report
+   details also supply tables and available result notes.
+2. Fix site/date scope. Warehouse `nsite_id` often resembles `Sites-Example-Site`;
+   verify it in `ccdw_dim_site` rather than constructing it from a SCAPI site ID.
+3. Run the report. Preview SQL only to adapt it or resolve an unclear definition.
+   Inspect table columns when custom SQL needs them; avoid exhaustive browsing.
+
+```bash
+b2c cip report list --category "Sales Analytics"
+b2c cip report sales-analytics --describe
+b2c cip report sales-analytics --site-id Sites-Example-Site --from 2026-09-01 --to 2026-09-07
+
+# Existing report does not fit: inspect the relevant table, then adapt SQL.
+b2c cip tables --pattern "ccdw_aggr_sales%"
+b2c cip describe ccdw_aggr_sales_summary
+b2c cip report sales-analytics --site-id Sites-Example-Site --from 2026-09-01 --to 2026-09-07 --sql
+
+# Execute a reviewed query; CLI replaces <FROM>/<TO> date placeholders.
+b2c cip query --file ./query.sql --from 2026-09-01 --to 2026-09-07 --format csv > sales.csv
+```
+
+Raw SQL also accepts a positional query or stdin. MCP SQL must contain literal
+dates; placeholder substitution is a CLI feature. Preserve exit status/errors
+when redirecting output. `--format table|csv|json` controls report/query output;
+`--json` uses the CLI's standard JSON envelope.
+
+## Select technical reports
+
+| Question | Report / constraint |
+| --- | --- |
+| Slow SCAPI endpoints | `scapi-latency-distribution`; histogram buckets describe a distribution, not exact percentiles |
+| HTTP failures | `scapi-error-rate-by-status --status-class 5xx` |
+| Cache effectiveness | `scapi-cache-hit-ratio` |
+| Integration client usage | `ocapi-client-usage` |
+| SFRA controllers | `controller-health-scorecard`, `controller-error-rate-trend`; site required |
+
+SCAPI traffic can be headless or unassigned. Omit optional site filters only for
+an intended all-site analysis; explain scope. Discover exact parameters with
+`--describe` instead of inventing flags. All examples require a chosen date window.
+
+## Query and interpret
+
+Filter dates/sites and select needed columns; LIMIT alone does not bound database
+work. Prefer aggregate tables over fact joins. Use summed revenue / summed orders
+for period AOV, not daily averages. Preserve null ratios, missing dates, currency,
+timezone, and coverage limits. Latest event date is not ingestion freshness.
+
+Safety Mode applies; CIP uses POST even for SELECT/metadata. Do not bypass a
+block. For 401/403, check credentials, role, and tenant filter without inferring
+that every denial is a missing role. For quota/timeouts, narrow the window or
+query; no retry loops. Official
+[access and service limits](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_access_guide.html).
+
+## Conditional references
+
+Read a matching section only when the task needs it:
+
+- Sales comparisons, gaps, latest activity: [SALES_ANALYSIS.md](references/SALES_ANALYSIS.md).
+- Custom SQL patterns: [STARTER_QUERIES.md](references/STARTER_QUERIES.md).
+- Unknown table family: [KNOWN_TABLES.md](references/KNOWN_TABLES.md), then live metadata.
+- CLI options: [command reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/cip).
+
+Stop once the requested result and material limitations are established.

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-cip/evals/trigger-evals.json

@@ -0,0 +1,12 @@
+[
+  {"query": "My manager wants a report on our January sales numbers from the production instance. I need to pull revenue and order count data broken down by day. How do I get this?", "should_trigger": true},
+  {"query": "I want to see what people are searching for on our storefront — top search terms and their conversion rates. Is there a way to pull search analytics from our commerce data?", "should_trigger": true},
+  {"query": "I need to run a custom SQL query against our commerce analytics data to calculate average order value by product category for Q4. What data tables are available and how do I query them?", "should_trigger": true},
+  {"query": "We're preparing for a quarterly business review and I need to export our key performance metrics — conversion rate, average basket size, and bounce rate — into a CSV for the last 90 days. How can I pull that programmatically?", "should_trigger": true},
+  {"query": "Our marketing team wants to understand which product categories are trending week-over-week. I need to query the analytics data to compare units sold and page views across categories for the past 6 weeks.", "should_trigger": true},
+  {"query": "I'm investigating a drop in checkout completion rate that started last Tuesday. I need to pull funnel metrics — sessions, add-to-carts, checkout starts, and orders — broken down hourly for the past 10 days so I can pinpoint when it changed.", "should_trigger": true},
+  {"query": "I need to export Page Designer content pages from our site library. How do I list and export them?", "should_trigger": false},
+  {"query": "My CLI isn't picking up the client credentials from dw.json. How do I debug the OAuth configuration?", "should_trigger": false},
+  {"query": "I need to query our product catalog to find all products in the 'electronics' category that have inventory below 10 units. Is there a way to search products via the API?", "should_trigger": false},
+  {"query": "How do I write a pipeline script that reads product data from the catalog and transforms it for an external feed?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-cip/references/KNOWN_TABLES.md

@@ -0,0 +1,105 @@
+# Known CIP Tables
+
+This quick catalog is based on the official JDBC schema documentation.
+
+Use this as a starting point. Always verify actual availability in your tenant with:
+
+```bash
+b2c cip tables --tenant-id <tenant-id>
+b2c cip describe <table-name> --tenant-id <tenant-id>
+```
+
+Official schema references:
+
+- https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_lakehouse_schema.html
+- https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_aggregate_tables.html
+- https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_dimension_tables.html
+- https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_fact_tables.html
+
+## Aggregate Tables (`ccdw_aggr_*`)
+
+Best for KPI/reporting use cases (already summarized):
+
+- [`ccdw_aggr_sales_summary`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_sales_summary.html)
+- [`ccdw_aggr_product_sales_summary`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_product_sales_summary.html)
+- [`ccdw_aggr_promotion_sales_summary`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_promotion_sales_summary.html)
+- [`ccdw_aggr_payment_sales_summary`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_payment_sales_summary.html)
+- [`ccdw_aggr_registration`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_registration.html)
+- [`ccdw_aggr_search`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_search.html)
+- [`ccdw_aggr_search_query`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_search_query.html)
+- [`ccdw_aggr_search_conversion`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_search_conversion.html)
+- [`ccdw_aggr_ocapi_request`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_ocapi_request.html)
+- [`ccdw_aggr_scapi_request`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_scapi_request.html)
+- [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_visit.html)
+- [`ccdw_aggr_visit_checkout`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_visit_checkout.html)
+- [`ccdw_aggr_visit_referrer`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_visit_referrer.html)
+- [`ccdw_aggr_visit_ip_address`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_visit_ip_address.html)
+- [`ccdw_aggr_visit_user_agent`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_visit_user_agent.html)
+- [`ccdw_aggr_visit_robot`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_visit_robot.html)
+- [`ccdw_aggr_controller_request`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_controller_request.html)
+- [`ccdw_aggr_include_controller_request`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_include_controller_request.html)
+- [`ccdw_aggr_source_code_activation`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_source_code_activation.html)
+- [`ccdw_aggr_source_code_sales`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_source_code_sales.html)
+- [`ccdw_aggr_product_cobuy`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_product_cobuy.html)
+- [`ccdw_aggr_product_recommendation`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_product_recommendation.html)
+- [`ccdw_aggr_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_product_recommendation_recommender.html)
+- [`ccdw_aggr_detail_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_detail_product_recommendation_recommender.html)
+- [`ccdw_aggr_daily_detail_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_daily_detail_product_recommendation_recommender.html)
+- [`ccdw_aggr_inventory_by_location`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_inventory_by_location.html)
+- [`ccdw_aggr_inventory_by_location_group`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_inventory_by_location_group.html)
+- [`ccdw_aggr_promotion_activation`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_promotion_activation.html)
+- [`ccdw_aggr_promotion_cobuy`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_promotion_cobuy.html)
+
+## Dimension Tables (`ccdw_dim_*`)
+
+Reference/context entities used for joins:
+
+- [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_site.html)
+- [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_product.html)
+- [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_customer.html)
+- [`ccdw_dim_campaign`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_campaign.html)
+- [`ccdw_dim_coupon`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_coupon.html)
+- [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_promotion.html)
+- [`ccdw_dim_payment_method`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_payment_method.html)
+- [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_business_channel.html)
+- [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_locale.html)
+- [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_geography.html)
+- [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_currency.html)
+- [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_source_code_group.html)
+- [`ccdw_dim_location`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_location.html)
+- [`ccdw_dim_location_group`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_location_group.html)
+- [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_date.html)
+- [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_time.html)
+- [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_timezone.html)
+- [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_user_agent.html)
+
+## Fact Tables (`ccdw_fact_*`)
+
+Most granular event-level tables (typically larger):
+
+- [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_line_item.html)
+- [`ccdw_fact_order_payments`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_order_payments.html)
+- [`ccdw_fact_customer_registration`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_customer_registration.html)
+- [`ccdw_fact_customer_list_snapshot`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_customer_list_snapshot.html)
+- [`ccdw_fact_promotion_line_item`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_promotion_line_item.html)
+- [`ccdw_fact_promotion_activation`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_promotion_activation.html)
+- [`ccdw_fact_source_codes_activation`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_source_codes_activation.html)
+- [`ccdw_fact_inventory_record_snapshot`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_inventory_record_snapshot.html)
+- [`ccdw_fact_inventory_record_snapshot_hourly`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_inventory_record_snapshot_hourly.html)
+- [`ccdw_fact_realtime_metric`](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_fact_realtime_metric.html)
+
+## Practical Starters
+
+When users ask for common analysis, start with:
+
+- **Sales trends:** `ccdw_aggr_sales_summary`
+- **Product performance:** `ccdw_aggr_product_sales_summary`, join `ccdw_dim_product`
+- **Promotion impact:** `ccdw_aggr_promotion_sales_summary`, join `ccdw_dim_promotion`
+- **Search conversion:** `ccdw_aggr_search_conversion`, `ccdw_aggr_search_query`
+- **Traffic source:** `ccdw_aggr_visit_referrer`
+- **API performance:** `ccdw_aggr_ocapi_request`, `ccdw_aggr_scapi_request`
+
+## Notes
+
+- Some doc pages may contain naming variance/typos (for example `..._couse` vs `..._cobuy`). Prefer actual tenant metadata output from `cip tables`.
+- Non-table helper objects may appear in some tenants (for example `all_calcite_types`).

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-cip/references/SALES_ANALYSIS.md

@@ -0,0 +1,50 @@
+# Sales comparisons and coverage
+
+Use only when interpreting sales gaps, comparing periods, or checking latest
+activity. Standard report execution needs no extra reference read.
+
+## Compare periods
+
+- Resolve natural `nsite_id` and numeric `site_id` from `ccdw_dim_site`.
+  Reuse verified IDs; do not derive one from a storefront identifier.
+- Use equal complete windows with explicit inclusive dates. State the calendar
+  week convention and timezone. Exclude an unfinished current week.
+- `sales-analytics` sums across daily dimensions. `sales-summary` preserves them;
+  individual rows are not daily totals. Apply report `resultNotes` when supplied.
+- Period AOV = summed revenue / summed orders, not the average of daily AOV.
+  Zero orders yields undefined AOV. Compute change only with a nonzero, comparable
+  baseline and adequate coverage; otherwise explain why it is unavailable.
+- `std_revenue` aggregates gross merchandise value in standard currency.
+  Tax/shipping are separate measures. Resolve the reporting currency and taxation
+  context before labeling amounts or comparing sites; do not assume net revenue.
+
+## Coverage check
+
+Run only if the user asks about freshness or returned dates leave a material gap.
+Replace the example site and dates with the resolved task scope. This is a bounded
+activity check, not an ingestion watermark or a count of zero-sales days.
+
+```sql
+SELECT CAST(MIN(ss.submit_date) AS VARCHAR) AS first_sales_date,
+       CAST(MAX(ss.submit_date) AS VARCHAR) AS latest_sales_date,
+       COUNT(DISTINCT ss.submit_date) AS days_with_rows
+FROM ccdw_aggr_sales_summary ss
+JOIN ccdw_dim_site s ON s.site_id = ss.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND ss.submit_date >= '2026-09-01'
+  AND ss.submit_date <= '2026-09-07'
+```
+
+Missing rows can mean no activity, unavailable data, or incomplete ingestion.
+Report which is known. A dimension's `last_update` does not establish freshness
+of sales aggregates. If no documented refresh marker is available, state unknown
+ingestion freshness and the latest activity date actually found in the window.
+Do not infer warehouse date semantics from a client's serialized `Z` suffix.
+
+## Definitions
+
+For unresolved field meaning, consult the specific official table article:
+[sales summary](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_sales_summary.html)
+or [site dimension](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_site.html).
+For access/availability, use the
+[analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac).

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-cip/references/STARTER_QUERIES.md

@@ -0,0 +1,147 @@
+# CIP Starter Queries
+
+Read only the section matching the custom analysis. Prefer a curated report
+when it already answers the task. For sales interpretation/coverage, use
+[Sales analysis](SALES_ANALYSIS.md).
+
+Replace `Sites-Example-Site` with a verified natural site ID. Replace `<FROM>` /
+`<TO>` with explicit inclusive dates before MCP execution. CLI `b2c cip query`
+can replace them using `--from` / `--to`. Discover columns before adapting a query.
+Date/site predicates bound the analysis; LIMIT only bounds returned rows.
+
+## 1) Recent Daily Sales Snapshot
+
+```sql
+SELECT ss.submit_date, SUM(ss.num_orders) AS orders,
+       SUM(ss.std_revenue) AS revenue
+FROM ccdw_aggr_sales_summary ss
+JOIN ccdw_dim_site s ON s.site_id = ss.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND ss.submit_date >= '<FROM>' AND ss.submit_date <= '<TO>'
+GROUP BY ss.submit_date
+ORDER BY ss.submit_date DESC
+LIMIT 20
+```
+
+## 2) Sales by Site (Joined)
+
+```sql
+SELECT ss.submit_date, ds.nsite_id, SUM(ss.num_orders) AS orders, SUM(ss.std_revenue) AS revenue
+FROM ccdw_aggr_sales_summary ss
+JOIN ccdw_dim_site ds ON ss.site_id = ds.site_id
+WHERE ds.nsite_id = 'Sites-Example-Site'
+  AND ss.submit_date >= '<FROM>' AND ss.submit_date <= '<TO>'
+GROUP BY ss.submit_date, ds.nsite_id
+ORDER BY ss.submit_date DESC
+LIMIT 30
+```
+
+## 3) Top-Selling Products by Revenue
+
+```sql
+SELECT p.nproduct_id, p.product_display_name, SUM(pss.std_revenue) AS revenue, SUM(pss.num_units) AS units
+FROM ccdw_aggr_product_sales_summary pss
+JOIN ccdw_dim_product p ON p.product_id = pss.product_id
+JOIN ccdw_dim_site s ON s.site_id = pss.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND pss.submit_date >= '<FROM>' AND pss.submit_date <= '<TO>'
+GROUP BY p.nproduct_id, p.product_display_name
+ORDER BY revenue DESC
+LIMIT 25
+```
+
+## 4) Promotion Impact Summary
+
+```sql
+SELECT p.promotion_class, SUM(pss.std_revenue) AS revenue, SUM(pss.std_total_discount) AS discount
+FROM ccdw_aggr_promotion_sales_summary pss
+JOIN ccdw_dim_promotion p ON p.promotion_id = pss.promotion_id
+JOIN ccdw_dim_site s ON s.site_id = pss.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND pss.submit_date >= '<FROM>' AND pss.submit_date <= '<TO>'
+GROUP BY p.promotion_class
+ORDER BY revenue DESC
+LIMIT 20
+```
+
+## 5) OCAPI Request Volume
+
+```sql
+SELECT request_date, api_name, api_resource, SUM(num_requests) AS total_requests, SUM(response_time) AS total_response_time
+FROM ccdw_aggr_ocapi_request a
+JOIN ccdw_dim_site s ON s.site_id = a.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND a.request_date >= '<FROM>' AND a.request_date <= '<TO>'
+GROUP BY request_date, api_name, api_resource
+ORDER BY request_date DESC, total_requests DESC
+LIMIT 25
+```
+
+## 6) SCAPI Request Volume
+
+Use a site filter only after verifying attribution; omit the site join/filter for
+an explicitly requested all-site analysis. Headless traffic may have no site.
+
+```sql
+SELECT request_date, api_name, api_resource, SUM(num_requests) AS total_requests, SUM(response_time) AS total_response_time
+FROM ccdw_aggr_scapi_request a
+JOIN ccdw_dim_site s ON s.site_id = a.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND a.request_date >= '<FROM>' AND a.request_date <= '<TO>'
+GROUP BY request_date, api_name, api_resource
+ORDER BY request_date DESC, total_requests DESC
+LIMIT 25
+```
+
+## 7) Top Search Terms by Revenue
+
+```sql
+SELECT LOWER(sc.query) AS search_term, SUM(sc.num_searches) AS searches, SUM(sc.num_orders) AS orders, SUM(sc.std_revenue) AS revenue
+FROM ccdw_aggr_search_conversion sc
+JOIN ccdw_dim_site s ON s.site_id = sc.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND sc.search_date >= '<FROM>' AND sc.search_date <= '<TO>'
+GROUP BY LOWER(sc.query)
+ORDER BY revenue DESC
+LIMIT 30
+```
+
+## 8) Referrer Mix
+
+```sql
+SELECT referrer_medium, referrer_source, SUM(num_visits) AS visits
+FROM ccdw_aggr_visit_referrer vr
+JOIN ccdw_dim_site s ON s.site_id = vr.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND vr.visit_date >= '<FROM>' AND vr.visit_date <= '<TO>'
+GROUP BY referrer_medium, referrer_source
+ORDER BY visits DESC
+LIMIT 30
+```
+
+## 9) Customer Registration Trend
+
+```sql
+SELECT registration_date, SUM(num_registrations) AS registrations
+FROM ccdw_aggr_registration r
+JOIN ccdw_dim_site s ON s.site_id = r.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND r.registration_date >= '<FROM>' AND r.registration_date <= '<TO>'
+GROUP BY registration_date
+ORDER BY registration_date DESC
+LIMIT 30
+```
+
+## 10) Payment Method Performance
+
+```sql
+SELECT pm.display_name AS payment_method, SUM(pss.num_payments) AS payments, SUM(pss.std_captured_amount) AS captured_amount
+FROM ccdw_aggr_payment_sales_summary pss
+JOIN ccdw_dim_payment_method pm ON pm.payment_method_id = pss.payment_method_id
+JOIN ccdw_dim_site s ON s.site_id = pss.site_id
+WHERE s.nsite_id = 'Sites-Example-Site'
+  AND pss.submit_date >= '<FROM>' AND pss.submit_date <= '<TO>'
+GROUP BY pm.display_name
+ORDER BY captured_amount DESC
+LIMIT 20
+```