docs: Update FAQ section with new information about VM IP bug and EasyOCR Certificate

docs/FAQ.md

@@ -29,6 +29,74 @@ No, macOS uses sparse files, which only allocate space as needed. For example, V
 lume delete <name>
 ```
 
+### How do I fix EasyOCR `[SSL: CERTIFICATE_VERIFY_FAILED]` errors?
+
+**Symptom:**
+When running an agent that uses OCR (e.g., with `AgentLoop.OMNI`), you might encounter an error during the first run or initialization phase that includes:
+```
+ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)
+```
+
+**Cause:**
+This usually happens when EasyOCR attempts to download its language models over HTTPS. Python's SSL module cannot verify the server's certificate because it can't locate the necessary root Certificate Authority (CA) certificates in your environment's trust store.
+
+**Solution:**
+You need to explicitly tell Python where to find a trusted CA bundle. The `certifi` package provides one. Before running your Python agent script, set the following environment variables in the *same terminal session*:
+```bash
+# Ensure certifi is installed: pip show certifi
+export SSL_CERT_FILE=$(python -m certifi)
+export REQUESTS_CA_BUNDLE=$(python -m certifi)
+
+# Now run your Python script that uses the agent...
+# python your_agent_script.py
+```
+This directs Python to use the CA bundle provided by `certifi` for SSL verification.
+
+### How do I troubleshoot the agent failing to get the VM IP address or getting stuck on "VM status changed to: stopped"?
+
+**Symptom:**
+When running your agent script (e.g., using `Computer().run(...)`), the script might hang during the VM startup phase, logging messages like:
+*   `Waiting for VM to be ready...`
+*   `VM status changed to: stopped (after 0.0s)`
+*   `Still waiting for VM IP address... (elapsed: XX.Xs)`
+*   Eventually, it might time out, or you might notice the VM window never appears or closes quickly.
+
+**Cause:**
+This is typically due to known instability issues with the `lume serve` background daemon process, as documented in the main `README.md`:
+1.  **`lume serve` Crash:** The `lume serve` process might terminate unexpectedly shortly after launch or when the script tries to interact with it. If it's not running, the script cannot get VM status updates or the IP address.
+2.  **Incorrect Status Reporting:** Even if `lume serve` is running, its API sometimes incorrectly reports the VM status as `stopped` immediately after startup is initiated. While the underlying `Computer` library tries to poll and wait for the correct `running` status, this initial incorrect report can cause delays or failures if the status doesn't update correctly within the timeout or if `lume serve` crashes during the polling.
+
+**Troubleshooting Steps:**
+1.  **Check `lume serve`:** Is the `lume serve` process still running in its terminal? Did it print any errors or exit? If it's not running, stop your agent script (`Ctrl+C`) and proceed to step 2.
+2.  **Force Cleanup:** Before *every* run, perform a rigorous cleanup to ensure no old `lume` processes or VM states interfere. Open a **new terminal** and run:
+    ```bash
+    # Stop any running Lume VM gracefully first (replace <vm_name> if needed)
+    lume stop macos-sequoia-cua_latest
+
+    # Force kill lume serve and related processes
+    pkill -f "lume serve"
+    pkill -9 -f "lume"
+    pkill -9 -f "VzVirtualMachine" # Kills underlying VM process
+
+    # Optional: Verify they are gone
+    # ps aux | grep -E 'lume|VzVirtualMachine' | grep -v grep
+    ```
+3.  **Restart Sequence:**
+    *   **Terminal 1:** Start `lume serve` cleanly:
+        ```bash
+        lume serve
+        ```
+        *(Watch this terminal to ensure it stays running).*
+    *   **Terminal 2:** Run your agent script (including the `export SSL_CERT_FILE...` commands if needed for OCR):
+        ```bash
+        export SSL_CERT_FILE=$(python -m certifi) # If using OCR
+        export REQUESTS_CA_BUNDLE=$(python -m certifi) # If using OCR
+        python your_agent_script.py
+        ```
+4.  **Retry:** Due to the intermittent nature of the Lume issues, sometimes simply repeating steps 2 and 3 allows the run to succeed if the timing avoids the status reporting bug or the `lume serve` crash.
+
+**Note:** Improving the stability of `lume serve` is an ongoing development area.
+
 ### How do I troubleshoot Computer not connecting to lume daemon?
 
 If you're experiencing connection issues between Computer and the lume daemon, it could be because the port 3000 (used by lume) is already in use by an orphaned process. You can diagnose this issue with: