docs(auth): clarify WebDAV Basic Auth is for user access, OAuth for API clients

Author: clavery

.changeset/webdav-auth-language.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-dx-docs': patch
+---
+
+Clarify WebDAV authentication guidance: Basic Auth is for interactive user-based access while OAuth is for API clients and CI/CD, rather than labeling Basic Auth as generally "recommended".

docs/guide/authentication.md

@@ -506,11 +506,14 @@ b2c scapi schemas list
 
 ## WebDAV Access
 
-WebDAV is required for file upload operations (`code deploy`, `code watch`, `webdav` commands).
+WebDAV is required for file upload operations (`code deploy`, `code watch`, `webdav` commands). There are two ways to authenticate, depending on who (or what) is connecting:
 
-### Option A: Basic Authentication (Recommended)
+- **Basic Authentication** — for individual developers using their own Business Manager account during interactive, local development.
+- **OAuth** — for API clients and automation (CI/CD pipelines, scripts) where no human is logging in.
 
-Use your Business Manager username and a WebDAV access key. These credentials provide better performance for file operations.
+### Option A: Basic Authentication (user access)
+
+Use your Business Manager username and a WebDAV access key. This is the simplest option for interactive, user-based access during local development.
 
 1. In Business Manager, go to **Administration** > **Organization** > **Users**
 2. Select your user
@@ -523,9 +526,9 @@ export SFCC_USERNAME=your-bm-username
 export SFCC_PASSWORD=your-webdav-access-key
 ```
 
-### Option B: OAuth-based WebDAV
+### Option B: OAuth-based WebDAV (API client access)
 
-If you prefer to use OAuth credentials for WebDAV (instead of basic auth), you must configure WebDAV Client Permissions:
+For API clients and automation (CI/CD), use OAuth credentials instead of a user's basic auth. This requires configuring WebDAV Client Permissions for the API client:
 
 1. Log in to Business Manager
 2. Navigate to **Administration** > **Organization** > **WebDAV Client Permissions**
@@ -604,8 +607,8 @@ Add the JSON configuration shown in [OCAPI Configuration](#ocapi-configuration)
 
 Either:
 
-- Use your BM username + WebDAV access key (recommended), or
-- Configure WebDAV Client Permissions for OAuth
+- Use your BM username + WebDAV access key (for user-based, interactive development), or
+- Configure WebDAV Client Permissions for OAuth (for API clients and CI/CD)
 
 ### 4. Set Environment Variables