Reorganize mail setup docs with Gmail instructions first

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

MAIL_SERVER_SETUP.md

@@ -1,6 +1,39 @@
-# Mail Server Setup for Testing
+# Mail Server Setup
 
-## Quick Start
+## Gmail Configuration
+
+### 1. Enable 2-Step Verification
+
+App Passwords require 2-Step Verification to be enabled on your Google account.
+
+1. Go to https://myaccount.google.com/security
+2. Under "How you sign in to Google", click **2-Step Verification**
+3. Follow the prompts to enable it
+
+### 2. Create an App Password
+
+1. Go to https://myaccount.google.com/apppasswords
+2. Enter a name (e.g. "Mail TUI") and click **Create**
+3. Google will display a 16-character password — copy it
+
+### 3. Update config.toml
+
+```toml
+[imap]
+host = "imap.gmail.com"
+port = 993
+username = "you@gmail.com"
+password = "xxxx xxxx xxxx xxxx"
+use_tls = true
+```
+
+Replace the password with the app password from step 2 (spaces are optional).
+
+**Important:** Do not commit `config.toml` — it is listed in `.gitignore`.
+
+## Local Test Server (Docker)
+
+### Quick Start
 
 1. **Start the mail server:**
    ```bash
@@ -17,14 +50,14 @@
    docker-compose ps
    ```
 
-## IMAP Connection Details
+### IMAP Connection Details
 
 - **Host:** localhost
 - **IMAP Port:** 143 (unencrypted) or 993 (SSL/TLS)
 - **Username:** test@example.com
 - **Password:** password123
 
-## Useful Commands
+### Useful Commands
 
 ```bash
 # Stop the mail server
@@ -46,7 +79,7 @@ docker exec -it mailserver setup email del test@example.com
 docker exec -it mailserver bash
 ```
 
-## Testing with telnet
+### Testing with telnet
 
 You can test IMAP connectivity:
 ```bash
@@ -61,7 +94,7 @@ a3 SELECT INBOX
 a4 LOGOUT
 ```
 
-## Send Test Email
+### Send Test Email
 
 ```bash
 # From within the container
@@ -73,6 +106,7 @@ Or use SMTP (port 25/587) from your application.
 
 ## Troubleshooting
 
-- Check logs: `docker-compose logs mailserver`
+- Gmail: if login fails, verify that 2-Step Verification is enabled and you're using an App Password (not your regular password)
+- Docker: check logs with `docker-compose logs mailserver`
 - Ensure ports aren't already in use
 - Data persists in `./docker-data/` directory