Clarify two-step workflow for Mail Import folder configuration

Enhanced Mail Import Setup documentation to clarify configuration workflow:

Step 2.1 (Enter Graph Credentials):
- Added warning callout: Must save credentials FIRST before folder configuration
- Credentials must be saved and page refreshed before Step 2.2 works

Step 2.2 (Configure Mail Folders):
- Added prerequisite: Ensure credentials saved and page refreshed
- Clarified folder browser popup AUTOMATICALLY loads folder structure
- Emphasized: Don't type paths manually - click folders in popup
- Folder browser connects to Microsoft Graph and retrieves folders
- Added callout: Folder browser auto-generates correct path format
- Added note about planned UI improvement for clearer workflow

Step 2.3 (Save Final Configuration):
- Renamed from "Save Settings" to "Save Final Configuration"
- Clarified this is the SECOND save (first was in 2.1)
- Added tip callout explaining two-step save process
- Enhanced error checking list (credentials, folders, access policy)

This clarifies the actual user workflow where credentials enable folder browsing.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

containers/backupchecks/src/templates/documentation/mail-import/setup.html

@@ -220,6 +220,11 @@
   The client secret field shows <code>******** (stored)</code> when a secret is already saved. Leave this field empty to keep the existing secret, or enter a new secret to replace it.
 </div>
 
+<div class="doc-callout doc-callout-warning">
+  <strong>⚠️ Important - Save Before Folder Configuration:</strong><br>
+  You <strong>must save the credentials first</strong> (click "Save settings" at the bottom) and refresh the page before you can configure folders in Step 2.2. The folder browser requires valid credentials to connect to your mailbox and retrieve the folder list.
+</div>
+
 <h3>2.2 Configure Mail Folders</h3>
 
 <p>BackupChecks uses two folders in the mailbox:</p>
@@ -249,29 +254,62 @@
 <p>To configure folders:</p>
 
 <ol>
+  <li><strong>Prerequisites:</strong> Ensure you've saved the credentials in Step 2.1 and refreshed the page</li>
   <li>Click the <strong>Browse...</strong> button next to the <strong>Incoming folder</strong> field</li>
-  <li>A folder browser dialog will open showing your mailbox folder structure</li>
+  <li>A folder browser popup will open and <strong>automatically load</strong> your mailbox folder structure
-  <li>Select the folder where backup reports arrive (e.g., <code>Inbox</code>)</li>
+    <ul>
-  <li>Click <strong>Select</strong></li>
+      <li>The popup connects to Microsoft Graph and retrieves all available folders</li>
-  <li>Repeat for the <strong>Processed folder</strong> (e.g., <code>Archive</code> or create a subfolder like <code>Inbox/Processed</code>)</li>
+      <li>You will see a hierarchical list of folders (Inbox, Archive, Sent Items, etc.)</li>
+    </ul>
+  </li>
+  <li><strong>Click</strong> on the folder where backup reports arrive (e.g., <code>Inbox</code>)
+    <ul>
+      <li>Don't type the path manually - select it from the list</li>
+      <li>You can expand subfolders by clicking on them</li>
+    </ul>
+  </li>
+  <li>Click <strong>Select</strong> to confirm your choice</li>
+  <li>The folder path will be automatically filled in the field (e.g., <code>Inbox</code> or <code>Inbox/Backup Reports</code>)</li>
+  <li>Repeat the same process for the <strong>Processed folder</strong> field
+    <ul>
+      <li>Click <strong>Browse...</strong> next to "Processed folder"</li>
+      <li>Select a folder like <code>Archive</code> or create a subfolder like <code>Inbox/Processed</code></li>
+    </ul>
+  </li>
 </ol>
 
-<div class="doc-callout doc-callout-warning">
+<div class="doc-callout doc-callout-info">
-  <strong>⚠️ Folder Structure:</strong><br>
+  <strong>💡 Folder Browser:</strong><br>
-  Folder paths are case-sensitive and use forward slashes (<code>/</code>) to separate levels. For example: <code>Inbox/Backup Reports</code> refers to a subfolder named "Backup Reports" inside the Inbox folder.
+  The folder browser automatically loads all available folders from your mailbox. You don't need to manually type folder paths - simply click on the folder you want to use. The correct path format (e.g., <code>Inbox/Backup Reports</code>) is automatically generated.
 </div>
 
-<h3>2.3 Save Settings</h3>
+<div class="doc-callout doc-callout-info">
+  <strong>📝 Future Improvement:</strong><br>
+  The current UI requires saving credentials separately before folder browsing is available. A UI improvement is planned to make this workflow clearer, possibly combining these steps or providing better visual feedback about the required order.
+</div>
 
-<p>After entering all credentials and folder paths:</p>
+<h3>2.3 Save Final Configuration</h3>
+
+<p>After configuring the folder paths:</p>
 
 <ol>
-  <li>Click <strong>Save settings</strong> at the bottom of the page</li>
+  <li>Click <strong>Save settings</strong> at the bottom of the page again</li>
-  <li>BackupChecks will validate the configuration</li>
+  <li>BackupChecks will validate the complete configuration (credentials + folders)</li>
   <li>If successful, you'll see a confirmation message</li>
-  <li>If there's an error, check your credentials and folder paths</li>
+  <li>If there's an error, verify:
+    <ul>
+      <li>Credentials are correct (tenant ID, client ID, client secret, mailbox address)</li>
+      <li>Folders exist in the mailbox and paths are correct</li>
+      <li>Application Access Policy (if configured) allows access to the mailbox</li>
+    </ul>
+  </li>
 </ol>
 
+<div class="doc-callout doc-callout-tip">
+  <strong>💡 Two Save Steps:</strong><br>
+  You'll save settings twice: first after entering credentials (Step 2.1), then again after selecting folders (Step 2.3). This ensures credentials are available for the folder browser to connect to your mailbox.
+</div>
+
 <h2>Step 3: Test the Configuration</h2>
 
 <p>After saving settings, verify that mail import is working:</p>

docs/changelog-claude.md

@@ -6,7 +6,7 @@ This file documents all changes made to this project via Claude Code.
 
 ### Added
 - Completed Mail & Import documentation section (4 pages):
-  - **Mail Import Setup**: Microsoft Graph API configuration with enhanced security (Azure AD app registration, start with Mail.Read only, Application Access Policy to restrict access to one mailbox via Exchange PowerShell, add Mail.ReadWrite after testing), folder configuration (incoming/processed), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), comprehensive security best practices including principle of least privilege
+  - **Mail Import Setup**: Microsoft Graph API configuration with enhanced security (Azure AD app registration, start with Mail.Read only, Application Access Policy to restrict access to one mailbox via Exchange PowerShell, add Mail.ReadWrite after testing), two-step folder configuration workflow (save credentials first, then use automatic folder browser popup - no manual path entry), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), comprehensive security best practices including principle of least privilege, note about planned UI improvement for clearer workflow
   - **Inbox Management**: Inbox overview and workflow, table columns explanation, viewing email details (metadata, body iframe, parsed objects), approving emails (customer selection, job name), what happens after approval, re-parsing emails (single and bulk), deleting emails (single and bulk delete, soft delete behavior), downloading .eml files, common workflows (new customer setup, troubleshooting unparsed emails, cleaning spam), best practices
   - **Mail Parsing**: Parsing overview and workflow (retrieval, preprocessing, parser selection, matching, parsing, storage), parsers (viewing available parsers, parser information), match criteria (sender, subject, body match), supported backup software (Veeam, Synology, NAKIVO, Boxafe, Panel3, QNAP, Syncovery, 3CX, RDrive, NTFS Auditing), parser execution order, enabling/disabling parsers, re-parsing emails, parsing workflow example, troubleshooting parsing issues, parser limitations, best practices
   - **Auto-Import Configuration**: Auto-import overview and features, enabling auto-import, import interval configuration (5/15/30/60 minutes), batch size explanation, how auto-import works (timer, check settings, authenticate, fetch, parse, auto-approve, move, log, persist, wait), auto-approval logic and conditions, when auto-approval fails, manual import (triggering, batch size 1-50), import settings summary table, monitoring import activity (audit log, inbox page, jobs/daily jobs), troubleshooting (auto-import not running, emails not auto-approved, import errors), best practices, advanced configuration (disabling temporarily, EML retention, high-volume environments)