feat: browser connection improvements (#601)

README.md

@@ -15,6 +15,7 @@
    1. [Main configuration](#main-config)
    1. [Ad configuration](#ad-config)
    1. [Using an existing browser window](#existing-browser)
+   1. [Browser Connection Issues](#browser-connection-issues)
 1. [Development Notes](#development)
 1. [Related Open-Source Projects](#related)
 1. [License](#license)
@@ -194,6 +195,7 @@ Commands:
   update-content-hash – recalculates each ad's content_hash based on the current ad_defaults;
                       use this after changing config.yaml/ad_defaults to avoid every ad being marked "changed" and republished
   create-config - creates a new default configuration file if one does not exist
+  diagnose - diagnoses browser connection issues and shows troubleshooting information
   --
   help     - displays this help (default command)
   version  - displays the application version
@@ -436,11 +438,31 @@ By default a new browser process will be launched. To reuse a manually launched
 
    This runs the browser in debug mode which allows it to be remote controlled by the bot.
 
-1. In your config.yaml specify the same flag as browser argument, e.g.:
+   **⚠️ IMPORTANT: Chrome 136+ Security Requirement**
+
+   Starting with Chrome 136 (March 2025), Google has implemented security changes that require `--user-data-dir` to be specified when using `--remote-debugging-port`. This prevents attackers from accessing the default Chrome profile and stealing cookies/credentials.
+
+   **You must now use:**
+   ```bash
+   chrome --remote-debugging-port=9222 --user-data-dir=/path/to/custom/directory
+   ```
+
+   **And in your config.yaml:**
+   ```yaml
+   browser:
+     arguments:
+       - --remote-debugging-port=9222
+       - --user-data-dir=/path/to/custom/directory
+     user_data_dir: "/path/to/custom/directory"
+   ```
+
+1. In your config.yaml specify the same flags as browser arguments, e.g.:
    ```yaml
    browser:
      arguments:
      - --remote-debugging-port=9222
+     - --user-data-dir=/tmp/chrome-debug-profile  # Required for Chrome 136+
+     user_data_dir: "/tmp/chrome-debug-profile"   # Must match the argument above
    ```
 
 1. When now publishing ads the manually launched browser will be re-used.
@@ -448,6 +470,24 @@ By default a new browser process will be launched. To reuse a manually launched
 > NOTE: If an existing browser is used all other settings configured under `browser` in your config.yaml file will ignored
   because they are only used to programmatically configure/launch a dedicated browser instance.
 
+> **Security Note:** This change was implemented by Google to protect users from cookie theft attacks. The custom user data directory uses a different encryption key than the default profile, making it more secure for debugging purposes.
+
+### <a name="browser-connection-issues"></a>Browser Connection Issues
+
+If you encounter browser connection problems, the bot includes a diagnostic command to help identify issues:
+
+**For binary users:**
+```bash
+kleinanzeigen-bot diagnose
+```
+
+**For source users:**
+```bash
+pdm run app diagnose
+```
+
+This command will check your browser setup and provide troubleshooting information. For detailed solutions to common browser connection issues, see the [Browser Connection Troubleshooting Guide](docs/BROWSER_TROUBLESHOOTING.md).
+
 ## <a name="development"></a>Development Notes
 
 > Please read [CONTRIBUTING.md](CONTRIBUTING.md) before contributing code. Thank you!