docs(skills): config-first idiomatic usage in CLI skill examples (#355)

* docs(skills): refactor skill examples for config-first idiomatic usage

Update b2c CLI skills so command examples assume configured values
(tenantId, shortCode, slasClientId, clientId, server) resolve from
dw.json / SFCC_* env vars, with flags shown only as overrides. This
prevents coding agents from prompting users for values that are
already present in their configuration.

Affected skills: scapi-schemas, scapi-custom, slas, ecdn (+ references),
cip, users-roles.

* feat(setup:skills): prompt to overwrite existing skills

When running interactively, detect already-installed skills and prompt
the user to overwrite them rather than requiring the --update flag
up front. Non-interactive behavior (--force, --update, --json)
is preserved.

Widen isSkillInstalled options to include the optional directory
override so the target-path check matches the installer's resolution
when --directory is provided.

Author: clavery

.changeset/setup-skills-upgrade-prompt.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+`b2c setup skills` now prompts to overwrite already-installed skills in interactive mode instead of silently skipping them with a "use --update to overwrite" message. The existing `--update` and `--force` flags still work non-interactively.

.changeset/skill-config-first-examples.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-cli': patch
+---
+
+Refine b2c CLI skills (`scapi-schemas`, `scapi-custom`, `slas`, `ecdn`, `cip`, `users-roles`) to show config-first idiomatic usage. Examples now assume values like `tenantId`, `shortCode`, and `clientId` are resolved from `dw.json` / `SFCC_*` env vars, with flags shown only as overrides. This prevents coding agents from prompting users for values that are already configured.

packages/b2c-cli/src/commands/setup/skills.ts

@@ -16,6 +16,7 @@ import {
   downloadSkillsArtifact,
   scanSkills,
   installSkills,
+  isSkillInstalled,
   getIdeDisplayName,
   getIdeDocsUrl,
   findSkillsByName,
@@ -305,6 +306,34 @@ export default class SetupSkills extends BaseCommand<typeof SetupSkills> {
       }
     }
 
+    // Detect already-installed skills and prompt to upgrade (unless --update or --force set)
+    let update = this.flags.update;
+    if (!update && !this.flags.force) {
+      const existingCount = skillsToInstall.reduce((count, skill) => {
+        return (
+          count +
+          targetIdes.filter((ide) =>
+            isSkillInstalled(skill.name, ide, {
+              global: this.flags.global,
+              projectRoot: process.cwd(),
+              directory,
+            }),
+          ).length
+        );
+      }, 0);
+
+      if (existingCount > 0) {
+        update = await confirm({
+          message: t(
+            'commands.setup.skills.confirmUpgrade',
+            '{{count}} skill(s) are already installed. Overwrite with the new version?',
+            {count: existingCount},
+          ),
+          default: true,
+        });
+      }
+    }
+
     // Install skills for all skillsets in parallel
     const installPromises = skillsets
       .map((skillset) => {
@@ -313,7 +342,7 @@ export default class SetupSkills extends BaseCommand<typeof SetupSkills> {
         return installSkills(skillsForSet, skillsDirs[skillset], {
           ides: targetIdes,
           global: this.flags.global,
-          update: this.flags.update,
+          update,
           projectRoot: process.cwd(),
           directory,
         });

packages/b2c-tooling-sdk/src/skills/installer.ts

@@ -88,7 +88,7 @@ async function copyDirectory(source: string, target: string): Promise<number> {
 export function isSkillInstalled(
   skillName: string,
   ide: IdeType,
-  options: {global: boolean; projectRoot?: string},
+  options: {global: boolean; projectRoot?: string; directory?: string},
 ): boolean {
   const installPath = getSkillInstallPath(ide, skillName, options);
   return fs.existsSync(installPath);

skills/b2c-cli/skills/b2c-cip/SKILL.md

@@ -29,16 +29,22 @@ cip
     └── top-referrers
 ```
 
-## Requirements
+## Configuration
 
-- OAuth client credentials (resolved from CLI configuration, or override with `--client-id` / `--client-secret`)
-- CIP tenant: `--tenant-id` (or `--tenant`)
-- API client has `Salesforce Commerce API` role with tenant filter for your instance
+Values like `tenantId`, `clientId`, and `clientSecret` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details.
 
-Optional:
+Relevant overrides:
 
-- `--cip-host` (or `SFCC_CIP_HOST`) to override the default host
-- `--staging` (or `SFCC_CIP_STAGING`) to force staging analytics host
+- `--tenant-id` (alias `--tenant`) / `SFCC_TENANT_ID` / `tenantId`
+- `--client-id` / `SFCC_CLIENT_ID` / `clientId`
+- `--client-secret` / `SFCC_CLIENT_SECRET` / `clientSecret`
+- `--cip-host` / `SFCC_CIP_HOST` to override the default host
+- `--staging` / `SFCC_CIP_STAGING` to force staging analytics host
+
+## Requirements
+
+- OAuth client credentials (CIP supports client credentials only; `--user-auth` is not supported)
+- API client has `Salesforce Commerce API` role with tenant filter for your instance
 
 ::: warning Availability
 This feature is typically used with production analytics tenants (for example `abcd_prd`).
@@ -58,14 +64,17 @@ Reports & Dashboards non-production URL: `https://ccac.stg.analytics.commerceclo
 ## Metadata Discovery Examples
 
 ```bash
-# List warehouse tables
-b2c cip tables --tenant-id abcd_prd
+# List warehouse tables (uses configured tenant)
+b2c cip tables
 
 # Filter table names
-b2c cip tables --tenant-id abcd_prd --pattern "ccdw_aggr_%"
+b2c cip tables --pattern "ccdw_aggr_%"
 
 # Describe table columns
-b2c cip describe ccdw_aggr_ocapi_request --tenant-id abcd_prd
+b2c cip describe ccdw_aggr_ocapi_request
+
+# Target a different tenant than the active config
+b2c cip tables --tenant-id abcd_prd
 ```
 
 ## Known Tables
@@ -86,9 +95,8 @@ The list is derived from official JDBC documentation and intended as a quick dis
 # Show report commands
 b2c cip report --help
 
-# Run a report
+# Run a report (tenant resolves from config)
 b2c cip report sales-analytics \
-  --tenant-id abcd_prd \
   --site-id Sites-RefArch-Site \
   --from 2025-01-01 \
   --to 2025-01-31
@@ -107,15 +115,13 @@ b2c cip report top-referrers --site-id Sites-RefArch-Site --limit 25 --staging -
 
 ```bash
 b2c cip report sales-analytics --site-id Sites-RefArch-Site --sql \
-  | b2c cip query --tenant-id abcd_prd
+  | b2c cip query
 ```
 
 ## Raw SQL Query Examples
 
 ```bash
-b2c cip query \
-  --tenant-id abcd_prd \
-  "SELECT * FROM ccdw_aggr_sales_summary LIMIT 10"
+b2c cip query "SELECT * FROM ccdw_aggr_sales_summary LIMIT 10"
 ```
 
 You can also use:

skills/b2c-cli/skills/b2c-ecdn/SKILL.md

@@ -9,72 +9,79 @@ Use the `b2c` CLI plugin to manage eCDN (embedded Content Delivery Network) zone
 
 > **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli ecdn zones list`).
 
+## Configuration
+
+Values like `tenantId` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details.
+
 ## Prerequisites
 
 - OAuth credentials with `sfcc.cdn-zones` scope (read operations)
 - OAuth credentials with `sfcc.cdn-zones.rw` scope (write operations)
-- Tenant ID for your B2C Commerce organization
+- Tenant ID for your B2C Commerce organization (from config or `--tenant-id`)
 
 ## Examples
 
 ### List CDN Zones
 
 ```bash
-# list all CDN zones for a tenant
-b2c ecdn zones list --tenant-id zzxy_prd
+# list all CDN zones for the configured tenant
+b2c ecdn zones list
+
+# JSON output
+b2c ecdn zones list --json
 
-# list with JSON output
-b2c ecdn zones list --tenant-id zzxy_prd --json
+# target a different tenant than the active config
+b2c ecdn zones list --tenant-id zzxy_prd
 ```
 
 ### Create a Storefront Zone
 
 ```bash
 # create a new storefront zone
-b2c ecdn zones create --tenant-id zzxy_prd --domain-name example.com
+b2c ecdn zones create --domain-name example.com
 ```
 
 ### Purge Cache
 
 ```bash
 # purge cache for specific paths
-b2c ecdn cache purge --tenant-id zzxy_prd --zone my-zone --path /products --path /categories
+b2c ecdn cache purge --zone my-zone --path /products --path /categories
 
 # purge by cache tags
-b2c ecdn cache purge --tenant-id zzxy_prd --zone my-zone --tag product-123 --tag category-456
+b2c ecdn cache purge --zone my-zone --tag product-123 --tag category-456
 ```
 
 ### Manage Certificates
 
 ```bash
 # list certificates for a zone
-b2c ecdn certificates list --tenant-id zzxy_prd --zone my-zone
+b2c ecdn certificates list --zone my-zone
 
 # add a new certificate
-b2c ecdn certificates add --tenant-id zzxy_prd --zone my-zone --hostname www.example.com --certificate-file ./cert.pem --private-key-file ./key.pem
+b2c ecdn certificates add --zone my-zone --hostname www.example.com --certificate-file ./cert.pem --private-key-file ./key.pem
 
 # validate a custom hostname
-b2c ecdn certificates validate --tenant-id zzxy_prd --zone my-zone --certificate-id abc123
+b2c ecdn certificates validate --zone my-zone --certificate-id abc123
 ```
 
 ### Security Settings
 
 ```bash
 # get security settings
-b2c ecdn security get --tenant-id zzxy_prd --zone my-zone
+b2c ecdn security get --zone my-zone
 
 # update security settings
-b2c ecdn security update --tenant-id zzxy_prd --zone my-zone --ssl-mode full --min-tls-version 1.2 --always-use-https
+b2c ecdn security update --zone my-zone --ssl-mode full --min-tls-version 1.2 --always-use-https
 ```
 
 ### Speed Settings
 
 ```bash
 # get speed optimization settings
-b2c ecdn speed get --tenant-id zzxy_prd --zone my-zone
+b2c ecdn speed get --zone my-zone
 
 # update speed settings
-b2c ecdn speed update --tenant-id zzxy_prd --zone my-zone --browser-cache-ttl 14400 --auto-minify-html --auto-minify-css
+b2c ecdn speed update --zone my-zone --browser-cache-ttl 14400 --auto-minify-html --auto-minify-css
 ```
 
 ## Additional Topics
@@ -84,12 +91,14 @@ For less commonly used eCDN features, see the reference files:
 - **[SECURITY.md](references/SECURITY.md)** — WAF (v1 and v2), custom firewall rules, rate limiting, and Page Shield (CSP policies, script detection, notification webhooks)
 - **[ADVANCED.md](references/ADVANCED.md)** — Logpush jobs, MRT routing rules, mTLS certificates, cipher suite configuration, and origin header modification
 
-## Configuration
+## Configuration Overrides
 
-The tenant ID can be set via environment variable:
-- `SFCC_TENANT_ID`: B2C Commerce tenant ID
+The tenant ID can be overridden via flag or environment variable:
+
+- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json
 
 The `--zone` flag accepts either:
+
 - Zone ID (32-character hex string)
 - Zone name (human-readable, case-insensitive lookup)
 

skills/b2c-cli/skills/b2c-ecdn/references/ADVANCED.md

@@ -2,79 +2,81 @@
 
 Logpush, MRT rules, mTLS, cipher suites, and origin header commands for B2C eCDN.
 
+> `tenantId` resolves from `dw.json` / `SFCC_TENANT_ID`. Add `--tenant-id` only to override the active config.
+
 ## Logpush
 
 ```bash
 # create ownership challenge for S3 destination
-b2c ecdn logpush ownership --tenant-id zzxy_prd --zone my-zone --destination-path 's3://my-bucket/logs?region=us-east-1'
+b2c ecdn logpush ownership --zone my-zone --destination-path 's3://my-bucket/logs?region=us-east-1'
 
 # list logpush jobs
-b2c ecdn logpush jobs list --tenant-id zzxy_prd --zone my-zone
+b2c ecdn logpush jobs list --zone my-zone
 
 # create a logpush job
-b2c ecdn logpush jobs create --tenant-id zzxy_prd --zone my-zone --name "HTTP logs" --destination-path 's3://my-bucket/logs?region=us-east-1' --log-type http_requests
+b2c ecdn logpush jobs create --zone my-zone --name "HTTP logs" --destination-path 's3://my-bucket/logs?region=us-east-1' --log-type http_requests
 
 # update a logpush job (enable/disable)
-b2c ecdn logpush jobs update --tenant-id zzxy_prd --zone my-zone --job-id 123456 --enabled
+b2c ecdn logpush jobs update --zone my-zone --job-id 123456 --enabled
 
 # delete a logpush job
-b2c ecdn logpush jobs delete --tenant-id zzxy_prd --zone my-zone --job-id 123456
+b2c ecdn logpush jobs delete --zone my-zone --job-id 123456
 ```
 
 ## MRT Rules
 
 ```bash
 # get MRT ruleset for a zone
-b2c ecdn mrt-rules get --tenant-id zzxy_prd --zone my-zone
+b2c ecdn mrt-rules get --zone my-zone
 
 # create MRT rules to route to a Managed Runtime environment
-b2c ecdn mrt-rules create --tenant-id zzxy_prd --zone my-zone --mrt-hostname customer-pwa.mobify-storefront.com --expressions '(http.host eq "example.com")'
+b2c ecdn mrt-rules create --zone my-zone --mrt-hostname customer-pwa.mobify-storefront.com --expressions '(http.host eq "example.com")'
 
 # update MRT ruleset hostname
-b2c ecdn mrt-rules update --tenant-id zzxy_prd --zone my-zone --mrt-hostname new-customer-pwa.mobify-storefront.com
+b2c ecdn mrt-rules update --zone my-zone --mrt-hostname new-customer-pwa.mobify-storefront.com
 
 # delete MRT ruleset
-b2c ecdn mrt-rules delete --tenant-id zzxy_prd --zone my-zone
+b2c ecdn mrt-rules delete --zone my-zone
 ```
 
 ## mTLS Certificates
 
 ```bash
 # list mTLS certificates (organization level)
-b2c ecdn mtls list --tenant-id zzxy_prd
+b2c ecdn mtls list
 
 # create mTLS certificate for code upload authentication
-b2c ecdn mtls create --tenant-id zzxy_prd --name "Build Server" --ca-certificate-file ./ca.pem --leaf-certificate-file ./leaf.pem
+b2c ecdn mtls create --name "Build Server" --ca-certificate-file ./ca.pem --leaf-certificate-file ./leaf.pem
 
 # get mTLS certificate details
-b2c ecdn mtls get --tenant-id zzxy_prd --certificate-id abc123
+b2c ecdn mtls get --certificate-id abc123
 
 # delete mTLS certificate
-b2c ecdn mtls delete --tenant-id zzxy_prd --certificate-id abc123
+b2c ecdn mtls delete --certificate-id abc123
 ```
 
 ## Cipher Suites
 
 ```bash
 # get cipher suites configuration
-b2c ecdn cipher-suites get --tenant-id zzxy_prd --zone my-zone
+b2c ecdn cipher-suites get --zone my-zone
 
 # update to Modern cipher suite
-b2c ecdn cipher-suites update --tenant-id zzxy_prd --zone my-zone --suite-type Modern
+b2c ecdn cipher-suites update --zone my-zone --suite-type Modern
 
 # update to Custom cipher suite with specific ciphers
-b2c ecdn cipher-suites update --tenant-id zzxy_prd --zone my-zone --suite-type Custom --ciphers "ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256"
+b2c ecdn cipher-suites update --zone my-zone --suite-type Custom --ciphers "ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256"
 ```
 
 ## Origin Headers
 
 ```bash
 # get origin header modification
-b2c ecdn origin-headers get --tenant-id zzxy_prd --zone my-zone
+b2c ecdn origin-headers get --zone my-zone
 
 # set origin header modification (for MRT)
-b2c ecdn origin-headers set --tenant-id zzxy_prd --zone my-zone --header-value my-secret-value
+b2c ecdn origin-headers set --zone my-zone --header-value my-secret-value
 
 # delete origin header modification
-b2c ecdn origin-headers delete --tenant-id zzxy_prd --zone my-zone
+b2c ecdn origin-headers delete --zone my-zone
 ```