diff --git a/docs/storage-r2.md b/docs/storage-r2.md
index 69db5436..27d237c0 100644
--- a/docs/storage-r2.md
+++ b/docs/storage-r2.md
@@ -23,6 +23,42 @@ file types include:
 The object key format is generated by `buildR2Key()` in `js/r2.js` and looks like:
 `u/<npub>/<YYYY>/<MM>/<slug>.<ext>`, which keeps uploads scoped by user and month.
 
+## Setup Guide: Getting your Cloudflare Credentials
+
+To enable R2 uploads, you must provide a Cloudflare API Token. This allows the app to automatically create buckets, configure CORS, and enable the public `r2.dev` domain for your videos.
+
+### Step 1: Get your Account ID
+1.  Log in to the **Cloudflare Dashboard**.
+2.  Navigate to **R2** in the sidebar.
+3.  Copy the **Account ID** from the right-hand sidebar.
+
+### Step 2: Create an S3 Access Key (for uploads)
+1.  In the R2 dashboard, click **Manage R2 API Tokens**.
+2.  Click **Create API token**.
+3.  Select **Admin Read & Write** permissions.
+4.  Click **Create API Token**.
+5.  Copy the **Access Key ID** and **Secret Access Key**.
+
+### Step 3: Create a Cloudflare API Token (for automation)
+1.  Go to **My Profile** > **API Tokens**.
+2.  Click **Create Token** -> **Custom Token** -> **Get started**.
+3.  **Token name:** e.g., "BitVid R2 Automation".
+4.  **Permissions:**
+    *   **Account** -> **Workers R2 Storage** -> **Edit**
+5.  **Account Resources:** Select your account.
+6.  Click **Continue to summary** -> **Create Token**.
+7.  Copy the token string.
+
+### Step 4: Configure the App
+1.  Open the Upload Modal in the app.
+2.  Expand **Storage Settings**.
+3.  Paste the **Account ID**.
+4.  Paste the **Access Key ID** and **Secret Access Key** (from Step 2).
+5.  Paste the **Cloudflare API Token** (from Step 3).
+6.  Click **Save**.
+
+The app is now ready to upload. It will automatically configure your bucket on the first upload.
+
 ## Upload lifecycle
 1. **Settings saved locally**
    - The Upload modal calls `r2Service.saveSettings()` to persist Cloudflare credentials and
diff --git a/js/services/r2Service.js b/js/services/r2Service.js
index c37819bb..65612bb8 100644
--- a/js/services/r2Service.js
+++ b/js/services/r2Service.js
@@ -426,7 +426,7 @@ class R2Service {
 
       if (!publicBaseUrl) {
         throw new Error(
-          "No public bucket domain configured. Add an API token or configure the domain manually."
+          "No public bucket domain configured. Please add a Cloudflare API token to automate domain setup."
         );
       }