clarity in docs and jsdocc

Author: clavery

docs/guide/configuration.md

@@ -86,7 +86,78 @@ You can configure authentication using environment variables:
 
 ## Configuration File
 
-You can create a configuration file to store instance settings. See the [CLI Reference](/cli/) for more details on configuration file options.
+You can create a `dw.json` file to store instance settings. The CLI searches for this file starting from the current directory and walking up the directory tree.
+
+### Single Instance
+
+```json
+{
+  "hostname": "your-instance.demandware.net",
+  "code-version": "version1",
+  "client-id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "client-secret": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+}
+```
+
+### Multiple Instances
+
+For projects that work with multiple instances, use the `configs` array:
+
+```json
+{
+  "configs": [
+    {
+      "name": "dev",
+      "active": true,
+      "hostname": "dev-instance.demandware.net",
+      "code-version": "version1",
+      "client-id": "dev-client-id"
+    },
+    {
+      "name": "staging",
+      "hostname": "staging-instance.demandware.net",
+      "code-version": "version1",
+      "client-id": "staging-client-id"
+    }
+  ]
+}
+```
+
+Use the `--instance` flag to select a specific configuration:
+
+```bash
+b2c code deploy --instance staging
+```
+
+If no instance is specified, the config with `"active": true` is used.
+
+### Supported Fields
+
+| Field | Description |
+|-------|-------------|
+| `hostname` | B2C instance hostname |
+| `webdav-hostname` | Separate hostname for WebDAV (if different) |
+| `code-version` | Code version for deployments |
+| `client-id` | OAuth client ID |
+| `client-secret` | OAuth client secret |
+| `username` | Basic auth username |
+| `password` | Basic auth password/access-key |
+| `scopes` | OAuth scopes (array or comma-separated string) |
+| `auth-methods` | Authentication methods in priority order |
+| `account-manager-host` | Custom Account Manager hostname |
+| `shortCode` | SCAPI short code |
+
+### Resolution Priority
+
+Configuration is resolved with the following precedence (highest to lowest):
+
+1. **CLI flags and environment variables** - Explicit values always take priority
+2. **dw.json** - Project configuration file
+3. **~/.mobify** - Home directory file (for MRT API key only)
+
+::: warning Hostname Mismatch Protection
+When you explicitly specify a hostname that differs from the `dw.json` hostname, the CLI ignores all other values from `dw.json` and only uses your explicit overrides. This prevents accidentally using credentials from one instance with a different server.
+:::
 
 ## Next Steps
 

packages/b2c-tooling-sdk/src/config/index.ts

@@ -27,16 +27,34 @@
  * const instance = resolver.createInstance({ hostname: '...' });
  * ```
  *
- * ## Lower-Level APIs
+ * ## Resolution Priority
  *
- * For advanced use cases, you can use the lower-level dw.json loading functions:
+ * Configuration is resolved with the following precedence (highest to lowest):
  *
- * ```typescript
- * import { loadDwJson, findDwJson } from '@salesforce/b2c-tooling-sdk/config';
+ * 1. **Explicit overrides** - Values passed to `resolve()`, `createInstance()`, etc.
+ * 2. **Configuration sources** - dw.json, ~/.mobify (in order)
  *
- * const dwJsonPath = findDwJson();
- * const config = loadDwJson({ path: dwJsonPath, instance: 'staging' });
- * ```
+ * Later sources only fill in missing values—they do not override values from
+ * higher-priority sources.
+ *
+ * ## Hostname Mismatch Protection
+ *
+ * The configuration system includes safety protection against accidentally using
+ * credentials from one instance with a different hostname. When you explicitly
+ * specify a hostname that differs from the dw.json hostname:
+ *
+ * - The entire base configuration from dw.json is ignored
+ * - Only your explicit overrides are used
+ * - A warning is included in the resolution result
+ *
+ * This prevents credential leakage between different B2C instances.
+ *
+ * ## Default Configuration Sources
+ *
+ * The default sources loaded by {@link createConfigResolver} are:
+ *
+ * - **dw.json** - Project configuration file, searched upward from cwd
+ * - **~/.mobify** - Home directory file for MRT API key
  *
  * ## Custom Configuration Sources
  *
@@ -53,6 +71,17 @@
  * const resolver = new ConfigResolver([new MySource()]);
  * ```
  *
+ * ## Lower-Level APIs
+ *
+ * For advanced use cases, you can use the lower-level dw.json loading functions:
+ *
+ * ```typescript
+ * import { loadDwJson, findDwJson } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const dwJsonPath = findDwJson();
+ * const config = loadDwJson({ path: dwJsonPath, instance: 'staging' });
+ * ```
+ *
  * @module config
  */
 

packages/b2c-tooling-sdk/src/config/mapping.ts

@@ -164,7 +164,19 @@ export function mergeConfigsWithProtection(
 
 /**
  * Gets the list of fields that have values in a config.
- * Used for tracking which sources contributed which fields.
+ *
+ * Used for tracking which sources contributed which fields during
+ * configuration resolution.
+ *
+ * @param config - The configuration to inspect
+ * @returns Array of field names that have non-empty values
+ *
+ * @example
+ * ```typescript
+ * const config = { hostname: 'example.com', clientId: 'abc' };
+ * const fields = getPopulatedFields(config);
+ * // ['hostname', 'clientId']
+ * ```
  */
 export function getPopulatedFields(config: NormalizedConfig): (keyof NormalizedConfig)[] {
   const fields: (keyof NormalizedConfig)[] = [];
@@ -184,6 +196,18 @@ export function getPopulatedFields(config: NormalizedConfig): (keyof NormalizedC
  *
  * @param config - The normalized configuration
  * @returns AuthConfig for B2CInstance
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   clientId: 'my-client-id',
+ *   clientSecret: 'my-secret',
+ *   username: 'admin',
+ *   password: 'pass',
+ * };
+ * const authConfig = buildAuthConfigFromNormalized(config);
+ * // { oauth: { clientId: '...', clientSecret: '...' }, basic: { username: '...', password: '...' } }
+ * ```
  */
 export function buildAuthConfigFromNormalized(config: NormalizedConfig): AuthConfig {
   const authConfig: AuthConfig = {