Update readme with stealth FAQ

cli/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "agent-browser-stealth"
-version = "0.15.1-fork.7"
+version = "0.15.1-fork.11"
 dependencies = [
  "base64",
  "dirs",

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agent-browser-stealth"
-version = "0.15.1-fork.7"
+version = "0.15.1-fork.11"
 edition = "2021"
 description = "Stealth browser automation CLI for AI agents with anti-bot evasions"
 license = "Apache-2.0"

cli/src/main.rs

@@ -399,6 +399,8 @@ fn main() {
         exit(1);
     }
 
+    let mut attached_to_existing_browser = false;
+
     // Auto-connect to existing browser
     if flags.auto_connect {
         let mut launch_cmd = json!({
@@ -436,6 +438,8 @@ fn main() {
             }
             exit(1);
         }
+
+        attached_to_existing_browser = true;
     }
 
     // Connect via CDP if --cdp flag is set
@@ -526,6 +530,8 @@ fn main() {
             }
             exit(1);
         }
+
+        attached_to_existing_browser = true;
     }
 
     // Launch with cloud provider if -p flag is set
@@ -567,8 +573,8 @@ fn main() {
     }
 
     // Project policy: when no explicit connection mode is provided,
-    // commands must attach to an existing browser on CDP :9333.
-    // If unavailable, fail fast instead of launching a managed browser.
+    // commands should attach to an existing browser.
+    // Try CDP :9333 first, then fall back to auto-connect discovery.
     let can_try_default_cdp = flags.cdp.is_none()
         && !flags.auto_connect
         && flags.provider.is_none()
@@ -581,7 +587,6 @@ fn main() {
         && !flags.allow_file_access
         && flags.extensions.is_empty();
 
-    let mut launched_via_default_cdp = false;
     if can_try_default_cdp {
         let mut launch_cmd = json!({
             "id": gen_id(),
@@ -594,11 +599,27 @@ fn main() {
         }
 
         if let Ok(resp) = send_command(launch_cmd, &flags.session) {
-            launched_via_default_cdp = resp.success;
+            attached_to_existing_browser = resp.success;
+        }
+
+        if !attached_to_existing_browser {
+            let mut auto_connect_cmd = json!({
+                "id": gen_id(),
+                "action": "launch",
+                "autoConnect": true
+            });
+
+            if let Some(ref cs) = flags.color_scheme {
+                auto_connect_cmd["colorScheme"] = json!(cs);
+            }
+
+            if let Ok(resp) = send_command(auto_connect_cmd, &flags.session) {
+                attached_to_existing_browser = resp.success;
+            }
         }
     }
-    if can_try_default_cdp && !launched_via_default_cdp {
-        let msg = "Project policy requires using your existing browser. Could not connect to CDP at localhost:9333. Start your browser with remote debugging on port 9333, or pass --cdp <port|url>.";
+    if can_try_default_cdp && !attached_to_existing_browser {
+        let msg = "Project policy requires using your existing browser. Could not connect to CDP at localhost:9333 and auto-discovery also failed. Start Chrome with remote debugging (for example, --remote-debugging-port=9333), or pass --cdp <port|url>.";
         if flags.json {
             println!(r#"{{"success":false,"error":"{}"}}"#, msg);
         } else {
@@ -621,7 +642,7 @@ fn main() {
         || flags.download_path.is_some())
         && flags.cdp.is_none()
         && flags.provider.is_none()
-        && !launched_via_default_cdp
+        && !attached_to_existing_browser
     {
         let mut launch_cmd = json!({
             "id": gen_id(),

cli/src/output.rs

@@ -2398,7 +2398,7 @@ Options:
   --headed                   Show browser window (not headless)
   --cdp <port>               Connect via CDP (Chrome DevTools Protocol)
   --auto-connect             Auto-discover and connect to running Chrome
-                             Project default: require existing browser at localhost:9333 (no auto local fallback)
+                             Project default: try localhost:9333 first, then auto-discovery (no managed local-launch fallback)
   --color-scheme <scheme>    Color scheme: dark, light, no-preference (or AGENT_BROWSER_COLOR_SCHEME)
   --download-path <path>     Default download directory (or AGENT_BROWSER_DOWNLOAD_PATH)
   --risk-mode <mode>         Verify/captcha handling: off, warn, block (or AGENT_BROWSER_RISK_MODE)
@@ -2416,7 +2416,7 @@ Options:
 Policy:
   --profile / AGENT_BROWSER_PROFILE are forbidden
   --channel / AGENT_BROWSER_CHANNEL are forbidden
-  Use existing browser session (CDP localhost:9333) or pass --cdp explicitly
+  Auto-attach existing browser (prefer CDP localhost:9333, then auto-discovery), or pass --cdp explicitly
 
 Configuration:
   agent-browser looks for agent-browser.json in these locations (lowest to highest priority):