Add b2c-setup skill and Realm Setup guide

.changeset/am-clients-create-confirm.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-agent-plugins': patch
+---
+
+`b2c am clients create` now shows the new client's details and asks for confirmation before creating it. Pass `--force` to skip the prompt; scripts and `--json` runs must add `--force`. New clients now default to `client_secret_basic`, so they work with their secret; previously Account Manager made them `private_key_jwt` and the secret was rejected. The `b2c-am` skill now walks your assistant through creating an API client when you don't have one, after you approve every detail.

.changeset/b2c-setup-skill.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-agent-plugins': minor
+'@salesforce/b2c-dx-mcp': minor
+---
+
+New `b2c-setup` skill guides your assistant through setting up a sandbox or realm: sample storefront datasets, search indexes, Storefront Next storefronts and project code, and replication to production, with confirmation before changes to shared instances. The MCP server features it in its skill listing.

.changeset/realm-setup-guide.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-dx-docs': patch
+---
+
+New Realm Setup guide covers sandbox and realm setup with the storefront datasets, Storefront Next storefronts, replication, and Safety Mode policies for shared instances. The Storefront Next guide now shows how to create a storefront and its API client from the CLI, generate the project code, get the `.env` file, and add production to an existing Managed Runtime project.

.changeset/staging-code-upload-notes.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-agent-plugins': patch
+'@salesforce/b2c-dx-docs': patch
+---
+
+Setup and code skills, and the Realm Setup guide, now explain that staging code upload normally requires a client certificate (a Salesforce Support CA bundle on legacy realms, or a self-registered eCDN CA on Hyperforce). They also cover the feature switch that Commerce API hooks need and how to reload when an instance has only one code version.

docs/.vitepress/config.mts

@@ -165,6 +165,7 @@ const guidesSidebar: DefaultTheme.SidebarItem[] = [
     text: 'Operations & Administration',
     collapsed: false,
     items: [
+      {text: 'Realm Setup', link: '/guide/realm-setup'},
       {text: 'Operations', link: '/guide/operations'},
       {text: 'Account Manager', link: '/guide/account-manager'},
       {text: 'Analytics Reports', link: '/guide/analytics-reports-cip-ccac'},

docs/cli/account-manager.md

@@ -826,6 +826,8 @@ When not using `--json`, displays formatted API client information including:
 
 Create a new Account Manager API client. Clients are created inactive by default and must be explicitly activated (e.g. via update).
 
+Before creating the client, the command shows its details (name, organizations, roles, role tenant filter, scopes, redirect URLs, auth method, and active state, but not the password) and asks for confirmation. Pass `--force` to skip the prompt in scripts; with `--json` or in a non-interactive session, `--force` is required.
+
 #### Usage
 
 ```bash
@@ -852,16 +854,20 @@ b2c am clients create [FLAGS]
 | `--scopes` | Comma-separated OAuth scopes |
 | `--default-scopes` | Comma-separated default OAuth scopes |
 | `--version-control` | Comma-separated version control system identifiers |
-| `--token-endpoint-auth-method` | Token endpoint auth method: `private_key_jwt`, `client_secret_post`, `client_secret_basic`, or `none` |
+| `--token-endpoint-auth-method` | Token endpoint auth method: `private_key_jwt`, `client_secret_post`, `client_secret_basic` (default), or `none` |
 | `--jwt-public-key` | Public key for JWT authentication (PEM or inline) |
-| `--json` | Output results as JSON |
+| `--force`, `-f` | Skip the confirmation prompt |
+| `--json` | Output results as JSON (requires `--force`) |
 
 #### Examples
 
 ```bash
 b2c am clients create --name my-client --orgs org-id-1 --password "SecureP@ss123"
 b2c am clients create -n my-client -o "My Organization" -p "SecureP@ss123" -r SALESFORCE_COMMERCE_API
 b2c am clients create -n my-client -o org-id-1 -p "SecureP@ss123" --scopes "mail,openid" --default-scopes "mail"
+
+# In a script, skip the confirmation prompt
+b2c am clients create -n my-client -o org-id-1 -p "SecureP@ss123" --force --json
 ```
 
 #### Notes
@@ -870,6 +876,7 @@ b2c am clients create -n my-client -o org-id-1 -p "SecureP@ss123" --scopes "mail
 - Password must be 12–128 characters
 - Role tenant filter must match pattern: `ROLE:realm_instance(,realm_instance)*(;ROLE:...)*` (e.g. SALESFORCE_COMMERCE_API:abcd_prd)
 - At least one organization ID is required
+- The token endpoint auth method defaults to `client_secret_basic`, so the client can authenticate with its password (client secret). Pass `--token-endpoint-auth-method private_key_jwt` with `--jwt-public-key` for [JWT authentication](/guide/authentication#jwt-authentication-certificate-based)
 
 ---
 

docs/cli/sfnext.md

@@ -18,7 +18,7 @@ To explore the template locally, use `npx` from outside an existing project:
 npx @salesforce/b2c-cli sfnext create-storefront
 ```
 
-This creates local project files; it does not provision the storefront's B2C Commerce and MRT resources. See [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-sf.html) for the local workflow.
+This creates local project files; it does not provision the storefront's B2C Commerce and MRT resources. To connect a generated project to a storefront on your instance, see [Generate the Project Code](/guide/storefront-next#generate-the-project-code). See [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-sf.html) for the local workflow.
 
 ## In-Project Commands
 

docs/guide/account-manager.md

@@ -157,21 +157,33 @@ b2c am users get developer@example.com --expand-all
 
 ### API Client Provisioning
 
-Create and configure API clients for your team or automation:
+Jobs, sites, Storefront Next storefronts, and other API commands need an API client. If you don't have one, create it with your own sign-in. You need the API Administrator or Account Administrator role in Account Manager.
 
 ```bash
-# Create an API client
-b2c am clients create \
+# Find your organization ID
+b2c am orgs list --user-auth
+
+# Create the client; the command shows its details and asks before creating it
+b2c am clients create --user-auth \
   --name "CI/CD Pipeline" \
   --orgs $ORG_ID \
-  --password "SecureP@ssword123" \
+  --password "$CLIENT_SECRET" \
   --roles SALESFORCE_COMMERCE_API \
-  --role-tenant-filter "SALESFORCE_COMMERCE_API:zzxy_prd"
-
-# Activate the client
-b2c am clients update $CLIENT_ID --active
+  --role-tenant-filter "SALESFORCE_COMMERCE_API:abcd_prd" \
+  --scopes "mail,roles,tenantFilter,openid,sfcc.jobs.rw,sfcc.sites" \
+  --default-scopes "mail,roles,tenantFilter,openid,sfcc.jobs.rw,sfcc.sites" \
+  --active
+
+# Save it for your instance
+b2c setup instance create staging --hostname staging-abcd-example.demandware.net \
+  --client-id $CLIENT_ID --client-secret "$CLIENT_SECRET" \
+  --short-code kv7kzm78 --tenant-id abcd_prd
 ```
 
+Grant only the tenants and scopes the client needs; [Scopes by Command](./authentication#scopes-by-command) lists them. Clients are inactive unless you pass `--active`; activate one later with `b2c am clients update $CLIENT_ID --active`. A client can be deleted only after it has been disabled for 7 days. For commands that use OCAPI, also add the client ID to [Open Commerce API Settings](./authentication#ocapi-configuration).
+
+When an AI assistant creates a client for you, the agent skills tell it to show you every detail and wait for your approval first.
+
 ### Bulk Operations with JSON Output
 
 Use `--json` output for scripting and integration with other tools:

docs/guide/authentication.md

@@ -54,6 +54,8 @@ Account Manager commands that manage organizations and API clients need roles on
 
 ### Creating an API Client
 
+To create the client from the CLI with your own sign-in, use [`b2c am clients create`](/cli/account-manager#b2c-am-clients-create). This requires the API Administrator or Account Administrator role; see [API Client Provisioning](./account-manager#api-client-provisioning). To create one in Account Manager:
+
 1. Log in to [Account Manager](https://account.demandware.com).
 2. Navigate to **API Client** in the left menu.
 3. Click **Add API Client**.
@@ -156,6 +158,10 @@ SCAPI Admin APIs need a client secret or JWT; browser sign-in isn't supported ye
 | `b2c sites list`, `sites cartridges list`             | `sfcc.sites` or `sfcc.sites.rw`        | [Sites](/cli/sites)                   |
 | `b2c sites cartridges add/remove/set`                 | `sfcc.sites.rw`                        | [Sites](/cli/sites)                   |
 | Catalog discovery used by export/VS Code              | `sfcc.catalogs` or `sfcc.catalogs.rw`  | [Jobs](/cli/jobs)                     |
+| `b2c mrt project list/get` (SCAPI backend)            | `sfcc.storefront.storefronts` or `.rw` | [MRT Backends](/cli/mrt#mrt-backends) |
+| `b2c mrt project create/update/delete` (SCAPI)        | `sfcc.storefront.storefronts.rw`       | [MRT Backends](/cli/mrt#mrt-backends) |
+| `b2c mrt env`, `env var` reads (SCAPI backend)        | `sfcc.storefront.environments`         | [MRT Backends](/cli/mrt#mrt-backends) |
+| `b2c mrt env`, `env var` writes (SCAPI backend)       | `sfcc.storefront.environments.rw`      | [MRT Backends](/cli/mrt#mrt-backends) |
 | `b2c mrt bundle history` (SCAPI backend)              | `sfcc.storefront.deployments` or `.rw` | [MRT Backends](/cli/mrt#mrt-backends) |
 | `b2c mrt bundle deploy <id>` (SCAPI backend)          | `sfcc.storefront.deployments.rw`       | [MRT Backends](/cli/mrt#mrt-backends) |
 

docs/guide/operations.md

@@ -27,6 +27,8 @@ investigations also need the [B2C CLI](./installation), Business Manager access,
 or information from an integration provider. See [authentication](./authentication)
 and [Safety Mode](./safety) for access and operation controls.
 
+To set up a new sandbox or realm, see [Realm Setup](./realm-setup).
+
 ## Understand settings and procedures
 
 Use [documentation search](../mcp/#b2c-commerce-documentation) to understand

docs/guide/realm-setup.md

@@ -0,0 +1,164 @@
+---
+description: Set up a new sandbox or realm with sample storefront data, search indexes, Storefront Next storefronts, and replication from staging to production.
+---
+
+# Realm Setup
+
+Take a new sandbox or realm from an empty instance to a working storefront with the B2C CLI and your AI assistant. Load a sample site from the storefront datasets, rebuild search indexes, set up a Storefront Next storefront, and replicate from staging to production.
+
+The `b2c-setup` skill guides your assistant through these steps. The [B2C MCP](../mcp/) features it, and the [b2c-cli plugin](./agent-skills#available-plugins) includes it.
+
+## Before You Start
+
+- Configure each instance: see [Configuration](./configuration). For a realm, add a named instance for staging, production, and any development instance.
+- Use an API client with access to every instance. See [Account Manager](./account-manager) and [Authentication](./authentication).
+- Check the setup with `b2c setup inspect -i <instance>`.
+
+### Protect Shared Instances
+
+Staging, production, and development are shared instances. A site import there can change global settings, such as active locales and the instance time zone, for every site. Production and development get code and data from staging by replication; do not import site data on them directly.
+
+Add a [Safety Mode](./safety) policy to each shared instance. With `confirm: true`, the CLI asks before an action the safety level blocks:
+
+```json
+{
+  "configs": [
+    {
+      "name": "sandbox",
+      "hostname": "abcd-001.dx.commercecloud.salesforce.com",
+      "safety": {"level": "NONE"}
+    },
+    {
+      "name": "staging",
+      "hostname": "staging-abcd-example.demandware.net",
+      "safety": {"level": "NO_DELETE", "confirm": true}
+    },
+    {
+      "name": "production",
+      "hostname": "production-abcd-example.demandware.net",
+      "safety": {"level": "READ_ONLY", "confirm": true}
+    }
+  ]
+}
+```
+
+See [per-instance policies](./safety#per-instance-configuration) and [confirmation](./safety#confirmation-mode). The `b2c-setup` skill also tells your assistant to name the target instance and wait for your approval before each change to a shared instance.
+
+## Storefront Datasets
+
+Salesforce publishes sample data for the reference storefronts in [storefront-datasets](https://github.com/SalesforceCommerceCloud/storefront-datasets). Each dataset is a site archive with a site, catalogs, price books, inventory, content, and promotions.
+
+The repository is available to Commerce Cloud customers and partners. To get access, link your GitHub account through Account Manager; see [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html). Without access, GitHub shows a 404 page for the repository.
+
+| Dataset directory  | Site ID        |
+| ------------------ | -------------- |
+| `foundations-data` | `Foundations`  |
+| `marketstreet`     | `MarketStreet` |
+| `beautynext`       | `BeautyNext`   |
+| `footwear-data`    | `Footwear`     |
+| `furniture-data`   | `Furniture`    |
+| `luxury-data`      | `Luxury`       |
+
+Releases are tagged with the Storefront Next template version they target, such as `v1.4.0`. Use the release that matches your storefront's template. Each release also attaches a ZIP per dataset.
+
+```bash
+git clone --branch v1.4.0 --depth 1 https://github.com/SalesforceCommerceCloud/storefront-datasets.git
+```
+
+`b2c job import` accepts a directory, so you do not need to zip a dataset first. Add `--split` if the upload is too large for one import. On an instance that already has sites, review the dataset's `preferences.xml` and other top-level files before you import it.
+
+## Set Up a Sandbox
+
+Sandboxes have no replication: import data and set up the storefront directly.
+
+```bash
+# Create a sandbox (billable) and save a connection for it
+b2c sandbox create --realm abcd --ttl 0 --wait
+b2c setup instance create my-sandbox --hostname abcd-001.dx.commercecloud.salesforce.com --active
+
+# Import a dataset and rebuild search indexes
+b2c job import ./storefront-datasets/marketstreet --show-log
+b2c job run Reindex --wait
+b2c sites list
+
+# Create a Storefront Next storefront for the site
+b2c mrt project create "Market Street" --site MarketStreet --mrt-backend scapi
+```
+
+The Foundations, Market Street, and Beauty Next datasets include a `Reindex` job. For other sites, run the system search index jobs; see [system jobs with custom request bodies](/cli/jobs#system-jobs-with-custom-request-bodies).
+
+Storefront creation runs asynchronously. Check progress with `b2c mrt project get -p <project-id> --mrt-backend scapi`, then get the project configuration from the storefront in Business Manager. You can also use **storefront setup in Business Manager** instead of `mrt project create`; see [Storefront Next](./storefront-next#start-with-storefront-setup).
+
+<ExamplePrompt>
+
+> Set up my sandbox my-sandbox with the Market Street dataset for Storefront Next 1.4.0: import it, rebuild the search indexes, and create a Storefront Next storefront for the site.
+
+</ExamplePrompt>
+
+## Set Up a Realm
+
+Set up staging completely, then replicate to production and development, then connect the storefront on each target.
+
+### 1. Prepare Staging
+
+Import your site data, or a dataset for a demo site, rebuild the search indexes, and create the storefront:
+
+```bash
+b2c job import ./storefront-datasets/marketstreet -i staging --show-log
+b2c job run Reindex -i staging --wait
+b2c mrt project create "Market Street" --site MarketStreet -i staging --mrt-backend scapi
+```
+
+For cartridge storefronts, deploy and activate a code version; see [code commands](/cli/code).
+
+Staging instances normally require two-factor (mTLS) code upload, so cartridge uploads without a client certificate fail, usually with `403 Forbidden`. On legacy realms, the client certificate is signed by a CA bundle from Salesforce Support and uploads go to the `cert.staging` hostname. On Hyperforce realms, you register your own CA through eCDN; see [Set Up Two-Factor Code Upload](/guide/hyperforce#set-up-two-factor-code-upload). To configure the certificate, see [Two-Factor Authentication](/guide/configuration#two-factor-authentication-mtls).
+
+If your cartridges register hooks for the Commerce API, also turn on hook execution in **Administration > Global Preferences > Feature Switches**. Otherwise the hooks don't run.
+
+### 2. Replicate to Production
+
+Replicate from staging with replication jobs in three steps: code, global data, then site data. Global data creates the site on the target, so on the first replication, run it before site data. The `b2c-replication` skill has the job definitions.
+
+```bash
+b2c job run Replicate-Code -i staging --wait --show-log
+b2c job run Replicate-Global -i staging --wait --show-log
+b2c job run Replicate-MarketStreet -i staging --wait --show-log
+```
+
+Replication changes production. Review what each job replicates before you run it.
+
+### 3. Connect the Storefront
+
+Storefronts do not replicate. Creating a storefront on production makes a second Managed Runtime project. To keep staging and production in one project, export the storefront from staging and import it on production:
+
+```bash
+b2c job export --storefront market-street -i staging --output ./storefront-export
+b2c job import ./storefront-export/<archive-name> -i production --wait-for-storefront --show-log
+```
+
+The storefront import requires the `user-id` in the export to be an Account Manager user who is authorized for the target. An export made with client credentials records the API client's service user; edit `user-id` before importing. Verify with `b2c mrt env list -p <project-id> -i production --mrt-backend scapi`. For all import requirements, see [Add Another Instance](./storefront-next#add-another-instance).
+
+<ExamplePrompt>
+
+> Our new realm has staging and production configured. Set up the Market Street dataset on staging with a Storefront Next storefront, then replicate it to production and connect the same Managed Runtime project there. Ask me before each change.
+
+</ExamplePrompt>
+
+## Troubleshooting
+
+| Problem                                                                           | What to check                                                       |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Import fails with a generic error                                                 | Rerun with `--show-log`; the cause is in the `[DATAERROR]` lines.   |
+| `There must be a root directory with the same name as the archive`                | Rename the ZIP or its root folder to match.                         |
+| Search returns no products                                                        | Rebuild the search indexes on that instance.                        |
+| First site replication fails with `Optimistic locking failure` or a generic error | Replicate global data first, then site data, as separate jobs.      |
+| Storefront import reports a user that is not authorized                           | Set `user-id` in the exported storefront XML to an authorized user. |
+
+When something fails after launch, see [Operations](./operations).
+
+## Related
+
+- [Storefront Next](./storefront-next) — environment variables, logs, and deployments after setup
+- [Operations](./operations) — job health and incident investigation
+- [Safety Mode](./safety) — policies and confirmation for shared instances
+- [Sandbox commands](/cli/sandbox), [Job commands](/cli/jobs), [MRT commands](/cli/mrt)

docs/guide/safety.md

@@ -413,6 +413,8 @@ array. This abbreviated example omits credentials:
 }
 ```
 
+For a realm setup example, see [Realm Setup](./realm-setup#protect-shared-instances).
+
 Confirm the target before requesting a change. CLI `-i production`, your
 assistant's selected target, and the IDE's instance picker can each select a
 different instance. A stricter environment or global level still applies.