@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/content/guidance/b2c-cli/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/content/guidance/b2c-cli/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/content/guidance/b2c-cli/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/content/guidance/b2c-cli/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
+```

package/content/guidance/b2c-cli/b2c-code/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: b2c-code
+description: Deploy, download, and manage cartridge code versions on B2C Commerce instances. Use this skill whenever the user needs to upload or download cartridges to/from a sandbox, activate or delete code versions, watch for local file changes during development, or deploy a subset of cartridges. Also use when pushing code to an instance, pulling code from an instance, or setting up a dev workflow with live reload -- even if they just say 'push my code to the sandbox', 'download the code', or 'how do I activate the new version'.
+---
+
+# B2C Code Skill
+
+Use the `b2c` CLI to deploy, download, and manage code versions on Salesforce B2C Commerce instances.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli code deploy`).
+
+## MCP equivalent
+
+Prefer `cartridge_deploy` for cartridge upload. Set `codeVersion` explicitly when
+needed; `files` selects up to 100 local files (64 MiB total), relative to
+`projectDirectory`, within discovered cartridges. Omit `files` for whole cartridges.
+Matching remote files are overwritten; selected-file mode preserves other files.
+`reload` may activate the target; keep upload success/warnings if reload fails.
+Code mode `builtin/code-version-inspect` reads active/rollback and activation metadata;
+`builtin/site-cartridge-inspect` reads site cartridge order and checks expected names.
+SCAPI `dx/scripts/v1` provides version management; `site/sites/v1` manages site paths.
+Use the CLI for watches, recursive downloads, and extra deployment flags.
+
+## 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`, `--client-secret`, `--username`, and `--password` 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.
+
+## Examples
+
+### Deploy Cartridges
+
+```bash
+# deploy all cartridges from current directory
+b2c code deploy
+
+# deploy cartridges from a specific directory
+b2c code deploy ./my-cartridges
+
+# deploy to a specific server and code version
+b2c code deploy --server my-sandbox.demandware.net --code-version v1
+
+# deploy and reload (re-activate) the code version
+b2c code deploy --reload
+
+# delete existing cartridges before upload and reload
+b2c code deploy --delete --reload
+
+# deploy only specific cartridges
+b2c code deploy -c app_storefront_base -c plugin_applepay
+
+# exclude specific cartridges from deployment
+b2c code deploy -x test_cartridge
+```
+
+### Download Cartridges
+
+```bash
+# download all cartridges from the active code version
+b2c code download
+
+# download to a specific directory
+b2c code download -o ./downloaded
+
+# download from a specific server and code version
+b2c code download --server my-sandbox.demandware.net --code-version v1
+
+# download only specific cartridges
+b2c code download -c app_storefront_base -c plugin_applepay
+
+# exclude specific cartridges from download
+b2c code download -x test_cartridge
+
+# mirror: extract to local cartridge project locations
+b2c code download --mirror
+```
+
+### Watch for Changes
+
+```bash
+# watch cartridges and upload changes automatically
+b2c code watch
+
+# watch a specific directory
+b2c code watch ./my-cartridges
+
+# watch with specific server and code version
+b2c code watch --server my-sandbox.demandware.net --code-version v1
+
+# watch only specific cartridges
+b2c code watch -c app_storefront_base
+
+# watch excluding specific cartridges
+b2c code watch -x test_cartridge
+```
+
+### List Code Versions
+
+```bash
+# list code versions on the instance
+b2c code list
+
+# list with JSON output
+b2c code list --json
+```
+
+### Activate Code Version
+
+```bash
+# activate a code version
+b2c code activate <version-name>
+
+# reload (re-activate) the current code version
+b2c code activate --reload
+```
+
+**Note:** Activation is idempotent. If the version is already active, the command succeeds without making a change. If you've uploaded code or changed Custom APIs in the active version, use `--reload` with deploy or activate to force a refresh and register the endpoints. Check registration status with the `b2c-cli:b2c-scapi-custom` skill.
+
+### Delete Code Version
+
+```bash
+# delete a code version
+b2c code delete <version-name>
+```
+
+### API Backend
+
+`code list`, `code activate`, `code delete`, and the active-version discovery / activate / reload steps in `code deploy` run over SCAPI. Configure `shortCode`, `tenantId`, and the `sfcc.scripts` / `sfcc.scripts.rw` scopes and they work out of the box. Read scope (`sfcc.scripts`) covers `code list` / discovery; write scope (`sfcc.scripts.rw`) covers activate, delete, reload, and the `--activate` / `--reload` flags on deploy.
+
+`code deploy` (file upload itself), `code download`, and `code watch` always use WebDAV — only the surrounding code-version operations use SCAPI.
+
+OCAPI is deprecated and disabled on newer instances. `--api-backend auto` (the default) falls back to the OCAPI Data API on safe SCAPI capability/auth/request rejections; force a backend with `--api-backend scapi|ocapi` if needed. The `--reload` flag forces a code cache reload as activate(alternate) + activate(target), using whichever backend the command selected — so it works on OCAPI-disabled instances when SCAPI is configured.
+
+### More Commands
+
+See `b2c code --help` for a full list of available commands and options in the `code` topic.
+
+> **Note:** `b2c code deploy` uploads cartridge _code_ to an instance. To manage which cartridges are _active on a site_ (the cartridge path), see the `b2c-cli:b2c-sites` skill for the `b2c sites cartridges` commands.
+
+## Related Skills
+
+- `b2c-cli:b2c-sites` - Manage site cartridge paths (list, add, remove, set active cartridges)
+- `b2c-cli:b2c-scapi-custom` - Check Custom API registration status after deployment
+- `b2c-cli:b2c-webdav` - Low-level file operations (delete cartridges, list files)
+- `b2c:b2c-custom-api-development` - Creating Custom API endpoints