chore: update the captcha doc with manual captcha solving

content/docs/overview/captchas-api/overview.mdx

@@ -19,6 +19,56 @@ CAPTCHA solving is particularly useful for:
 *   AI agents that need to navigate CAPTCHA-protected websites
 
 
+### Session Configuration
+
+To enable autosolving, simply set `solveCaptcha: true` when creating a session.
+
+<CodeTabs storage="languageSwitcher">
+
+```typescript !! Typescript -wcn
+import Steel from 'steel-sdk';
+
+const client = new Steel();
+
+const session = await client.sessions.create({
+  solveCaptcha: true
+});
+```
+
+```python !! Python -wcn
+from steel import Steel
+
+client = Steel()
+session = client.sessions.create(
+    solve_captcha=True
+)
+```
+</CodeTabs>
+
+To detect CAPTCHAs without automatically solving them, disable `autoCaptchaSolving` in the stealth config:
+
+<CodeTabs storage="languageSwitcher">
+
+```typescript !! Typescript -wcn
+const session = await client.sessions.create({
+  solveCaptcha: true,
+  stealthConfig: {
+    autoCaptchaSolving: false
+  }
+});
+```
+
+```python !! Python -wcn
+session = client.sessions.create(
+    solve_captcha=True,
+    stealth_config={
+        "autoCaptchaSolving": False
+    }
+)
+```
+</CodeTabs>
+
+
 ### How CAPTCHA Solving Works with the CAPTCHAs API
 
 Steel's CAPTCHAs API operates through a bridge architecture that connects your browser sessions with our external CAPTCHA-solving capabilities. It helps with four key parts:
@@ -76,11 +126,15 @@ The status endpoint returns an array of current pages and their CAPTCHA states.
             "type":"image_to_text",
             "status":"solving",
             "created":1640995200000,
-            "totalDuration":5000
+            "url":"https://example.com/login",
+            "pageId":"page_12345",
+            "detectionTime":1640995200500,
+            "totalDuration":5000,
+            "solveTime":1640995205500
          }
       ],
       "created":1640995200000,
-      "lastUpdated":1640995205000
+      "lastUpdated":1640995205500
    }
 ]
 ```
@@ -95,6 +149,8 @@ Tasks can have the following statuses:
 
 *   `validating`: CAPTCHA is currently being validated
 
+*   `validation_failed`: CAPTCHA token failed validation after submission
+
 *   `solving`: CAPTCHA is currently being solved
 
 *   `solved`: CAPTCHA has been successfully solved
@@ -104,6 +160,44 @@ Tasks can have the following statuses:
 *   `failed_to_solve`: CAPTCHA solving failed
 
 
+### Manual Solving
+
+If auto-solving is disabled, use the solve endpoint to trigger solving. You can solve all detected CAPTCHAs or target specific ones.
+
+The `taskId`, `url`, and `pageId` required for targeting specific CAPTCHAs can be retrieved from the CAPTCHA status response. When using `taskId`, use the value from the task's `id` field.
+
+<CodeTabs storage="languageSwitcher">
+
+```typescript !! Typescript -wcn
+// Solve all detected CAPTCHAs
+await client.sessions.captchas.solve('sessionId');
+
+// Solve specific task
+await client.sessions.captchas.solve('sessionId', { taskId: 'task_123' });
+
+// Solve by URL
+await client.sessions.captchas.solve('sessionId', { url: 'https://example.com' });
+
+// Solve by Page ID
+await client.sessions.captchas.solve('sessionId', { pageId: 'page_123' });
+```
+
+```python !! Python -wcn
+# Solve all detected CAPTCHAs
+client.sessions.captchas.solve("sessionId")
+
+# Solve specific task
+client.sessions.captchas.solve("sessionId", task_id="task_123")
+
+# Solve by URL
+client.sessions.captchas.solve("sessionId", url="https://example.com")
+
+# Solve by Page ID
+client.sessions.captchas.solve("sessionId", page_id="page_123")
+```
+</CodeTabs>
+
+
 ### Solving Image CAPTCHAs
 
 For image-based CAPTCHAs, you can provide XPath selectors to help the system locate and solve the CAPTCHA.

content/docs/overview/stealth/captcha-solving.mdx

@@ -77,29 +77,95 @@ When you enable CAPTCHA solving in your Steel session, here's what happens behin
 5.  **Verification**: The system verifies that the CAPTCHA was successfully solved before allowing the session to continue.
 
 
-### Best Practices for Implementation
+### Session Configuration
 
-#### 1\. Enable CAPTCHA Solving
+To enable autosolving, simply set `solveCaptcha: true` when creating a session.
 
 <CodeTabs storage="languageSwitcher">
 
-```typescript !! Typescript -wc
-// Typescript
+```typescript !! Typescript -wcn
+import Steel from 'steel-sdk';
+
+const client = new Steel();
+
+const session = await client.sessions.create({
+  solveCaptcha: true
+});
+```
+
+```python !! Python -wcn
+from steel import Steel
+
+client = Steel()
+session = client.sessions.create(
+    solve_captcha=True
+)
+```
+</CodeTabs>
+
+To detect CAPTCHAs without automatically solving them, disable `autoCaptchaSolving` in the stealth config:
+
+<CodeTabs storage="languageSwitcher">
+
+```typescript !! Typescript -wcn
 const session = await client.sessions.create({
-    solveCaptcha: true  // Enable CAPTCHA solving
+  solveCaptcha: true,
+  stealthConfig: {
+    autoCaptchaSolving: false
+  }
 });
 ```
 
 ```python !! Python -wcn
-# Python
 session = client.sessions.create(
-    solve_captcha=True  # Enable CAPTCHA solving
+    solve_captcha=True,
+    stealth_config={
+        "autoCaptchaSolving": False
+    }
 )
 ```
 </CodeTabs>
 
+### Manual Solving
+
+If auto-solving is disabled, use the solve endpoint to trigger solving. You can solve all detected CAPTCHAs or target specific ones.
+
+The `taskId`, `url`, and `pageId` required for targeting specific CAPTCHAs can be retrieved from the [CAPTCHA status response](/overview/captchas-api/overview#getting-captcha-status). When using `taskId`, use the value from the task's `id` field.
+
+<CodeTabs storage="languageSwitcher">
+
+```typescript !! Typescript -wcn
+// Solve all detected CAPTCHAs
+await client.sessions.captchas.solve('sessionId');
+
+// Solve specific task
+await client.sessions.captchas.solve('sessionId', { taskId: 'task_123' });
+
+// Solve by URL
+await client.sessions.captchas.solve('sessionId', { url: 'https://example.com' });
+
+// Solve by Page ID
+await client.sessions.captchas.solve('sessionId', { pageId: 'page_123' });
+```
+
+```python !! Python -wcn
+# Solve all detected CAPTCHAs
+client.sessions.captchas.solve("sessionId")
+
+# Solve specific task
+client.sessions.captchas.solve("sessionId", task_id="task_123")
+
+# Solve by URL
+client.sessions.captchas.solve("sessionId", url="https://example.com")
+
+# Solve by Page ID
+client.sessions.captchas.solve("sessionId", page_id="page_123")
+```
+</CodeTabs>
+
+### Best Practices for Implementation
 
-#### 2\. Implement Proper Waiting
+#### 1\. Implement Proper Waiting
 
 When navigating to pages that might contain CAPTCHAs, it's important to implement proper waiting strategies:
 
@@ -118,7 +184,7 @@ await page.wait_for_timeout(2000)  # Additional safety buffer
 ```
 </CodeTabs>
 
-#### 3\. Detecting CAPTCHA Presence
+#### 2. Detecting CAPTCHA Presence
 
 You can detect CAPTCHA presence using these selectors: