Fix macOS SSL cert issue, add troubleshooting and upgrade docs

- Add SSL certificate auto-fix in FaceProtector (certifi)
- Add Troubleshooting section to README (SSL, first-run downloads)
- Add upgrade instructions for pipx/uv tool users

README.md

@@ -33,6 +33,14 @@ pipx install git+https://github.com/wiltodelta/remove-ai-watermarks.git
 uv tool install git+https://github.com/wiltodelta/remove-ai-watermarks.git
 ```
 
+To update to the latest version:
+
+```bash
+pipx upgrade remove-ai-watermarks
+# or
+uv tool upgrade remove-ai-watermarks
+```
+
 ### Install from repository (macOS)
 
 **Prerequisites:** Python 3.10+ and `pip` (or [`uv`](https://docs.astral.sh/uv/)).
@@ -137,6 +145,20 @@ if has_ai_metadata(Path("image.png")):
 - **Visible removal / metadata**: CPU only, no GPU required
 - **Invisible removal**: GPU recommended (CUDA or MPS), works on CPU (slow)
 
+## Troubleshooting
+
+**SSL certificate error on macOS** (`CERTIFICATE_VERIFY_FAILED`):
+
+```bash
+# Option 1: Run the Python certificate installer
+/Applications/Python\ 3.*/Install\ Certificates.command
+
+# Option 2: Install certifi (the tool auto-detects it)
+pip install certifi
+```
+
+**First run is slow** — this is expected. The tool downloads model weights (~2 GB) on first launch. Subsequent runs use cached models.
+
 ## Credits
 
 - [noai-watermark](https://github.com/mertizci/noai-watermark) by mertizci — invisible watermark removal engine

src/remove_ai_watermarks/face_protector.py

@@ -27,6 +27,8 @@ class FaceProtector:
         self.haar_cascade = None
 
         if self.use_yolo:
+            # Fix SSL certificate issues on macOS (fresh Python installs)
+            self._fix_ssl_certs()
             logger.info(f"Loading YOLO model '{model_name}' for face protection...")
             self.detector = YOLO(model_name)
         else:
@@ -71,6 +73,20 @@ class FaceProtector:
                 bboxes.append((x1, y1, x2, y2))
             return bboxes
 
+    @staticmethod
+    def _fix_ssl_certs() -> None:
+        """Set SSL_CERT_FILE from certifi if not already set (macOS fix)."""
+        import os
+
+        if os.environ.get("SSL_CERT_FILE"):
+            return
+        try:
+            import certifi
+
+            os.environ["SSL_CERT_FILE"] = certifi.where()
+        except ImportError:
+            pass
+
     def extract_faces(self, image: np.ndarray) -> list[tuple[tuple[int, int, int, int], np.ndarray]]:
         """
         Extract faces from the image.